Go SDK Reference: mcpgateway

Overview

The mcpgateway package is a single-purpose Go module for communicating with the PRECINCT gateway. It requires Go ≥1.24.6 and has exactly one external dependency: github.com/google/uuid (used to auto-generate session IDs).

• Module path: github.com/RamXX/agentic_reference_architecture/POC/sdk/go
• Package: mcpgateway
• Go version: ≥1.24.6
• Dependencies: github.com/google/uuid

The package exposes three public types (GatewayClient, GatewayError, ModelChatRequest), a constructor (NewClient), functional option helpers (With*), and three default-value constants.

Installation

From the Repository

go get github.com/RamXX/agentic_reference_architecture/POC/sdk/go/mcpgateway

Local Development (replace directive)

When developing alongside the PRECINCT mono-repo, use a replace directive in your go.mod to point at the local checkout:

// go.mod
module myagent

go 1.24.6

require github.com/RamXX/agentic_reference_architecture/POC/sdk/go v0.0.0

replace github.com/RamXX/agentic_reference_architecture/POC/sdk/go => ../agentic_reference_architecture/POC/sdk/go

go mod tidy

Quick Start

package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/RamXX/agentic_reference_architecture/POC/sdk/go/mcpgateway"
)

func main() {
    // Create a client with gateway URL and SPIFFE identity.
    client := mcpgateway.NewClient(
        "http://localhost:9090",
        "spiffe://poc.local/agents/mcp-client/researcher/dev",
    )

    ctx := context.Background()

    // Call a tool. The SDK auto-wraps this as tools/call JSON-RPC.
    result, err := client.Call(ctx, "tavily_search", map[string]any{
        "query": "AI security best practices",
    })
    if err != nil {
        var ge *mcpgateway.GatewayError
        if errors.As(err, &ge) {
            log.Fatalf("gateway denied (code=%s, middleware=%s, step=%d): %s",
                ge.Code, ge.Middleware, ge.Step, ge.Message)
        }
        log.Fatal(err)
    }
    fmt.Println(result)
}

GatewayClient API

NewClient

func NewClient(url, spiffeID string, opts ...Option) *GatewayClient

Creates a new GatewayClient targeting the given gateway base URL (e.g., "http://localhost:9090"). The spiffeID is sent in the X-SPIFFE-ID header on every request for authentication.

If no WithSessionID option is provided, a random UUID is generated automatically. If no WithHTTPClient option is provided, a default *http.Client is created with the configured timeout.

Call

func (c *GatewayClient) Call(ctx context.Context, methodOrTool string, params map[string]any) (any, error)

Invokes a tool or protocol method through the gateway using MCP-spec JSON-RPC 2.0.

Auto-detection logic: Call inspects the methodOrTool argument to decide the wire format:

• If the string contains a / separator (e.g., "tools/list", "resources/read") or equals "initialize" or starts with "notifications/", it is treated as a protocol method and sent verbatim as the JSON-RPC method field.
• Otherwise (e.g., "tavily_search", "calculator"), it is treated as a tool name. The SDK automatically wraps it using the MCP-spec envelope: method="tools/call", params.name=<tool>, params.arguments=<params>.

// Tool invocation (most common): auto-wrapped as tools/call
result, err := client.Call(ctx, "tavily_search", map[string]any{
    "query": "SPIFFE mTLS",
})

// Protocol method: sent verbatim
result, err := client.Call(ctx, "tools/list", nil)

// Initialize handshake
result, err := client.Call(ctx, "initialize", map[string]any{
    "protocolVersion": "2024-11-05",
    "capabilities":    map[string]any{},
    "clientInfo": map[string]any{
        "name":    "my-agent",
        "version": "1.0.0",
    },
})

On success, the JSON-RPC result field is returned as any (typically map[string]any). On gateway denial or error, a *GatewayError is returned. Use errors.As to inspect it.

CallModelChat

func (c *GatewayClient) CallModelChat(ctx context.Context, req ModelChatRequest) (map[string]any, error)

Sends an OpenAI-compatible chat completion request through the gateway model egress endpoint. This bypasses JSON-RPC and sends a direct HTTP POST with model-plane headers. See ModelChatRequest for the full field reference.

SessionID

func (c *GatewayClient) SessionID() string

Returns the session ID used by this client instance. Useful for logging or correlating requests across multiple tool calls within a single session.

Configuration Options

GatewayClient uses the functional options pattern. Each With* function returns an Option value that customizes the client.

client := mcpgateway.NewClient(
    "http://localhost:9090",
    "spiffe://poc.local/agents/mcp-client/researcher/dev",
    mcpgateway.WithSessionID("session-abc-123"),
    mcpgateway.WithTimeout(60*time.Second),
    mcpgateway.WithMaxRetries(5),
    mcpgateway.WithBackoffBase(500*time.Millisecond),
)

ModelChatRequest

ModelChatRequest captures all options for an OpenAI-compatible chat completion request routed through the gateway model egress plane.

resp, err := client.CallModelChat(ctx, mcpgateway.ModelChatRequest{
    Model: "llama-3.3-70b-versatile",
    Messages: []map[string]any{
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is SPIFFE?"},
    },
    Provider:  "groq",
    APIKeyRef: "Bearer gsk_...",
    ExtraPayload: map[string]any{
        "temperature": 0.7,
        "max_tokens":  512,
    },
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(resp["choices"])

GatewayError

GatewayError is a structured error type that mirrors the unified JSON error envelope returned by every gateway middleware denial. It implements the error interface.

Error() Method

The Error() method returns a formatted string. The format depends on which fields are populated:

# When Message is set:
gateway error authz_policy_denied: request denied by OPA policy

# When only Code is set:
gateway error authz_policy_denied

# When neither Code nor Message is set:
gateway error (HTTP 403)

Using errors.As

result, err := client.Call(ctx, "tavily_search", params)
if err != nil {
    var ge *mcpgateway.GatewayError
    if errors.As(err, &ge) {
        log.Printf("code=%s middleware=%s step=%d decision=%s trace=%s",
            ge.Code, ge.Middleware, ge.Step, ge.DecisionID, ge.TraceID)
        if ge.Remediation != "" {
            log.Printf("remediation: %s", ge.Remediation)
        }
        if ge.Details != nil {
            log.Printf("details: %v", ge.Details)
        }
    } else {
        // Network error, context cancelled, etc.
        log.Printf("non-gateway error: %v", err)
    }
}

Error Code Catalog

Every gateway middleware denial returns one of the following machine-readable error codes in the GatewayError.Code field. The full catalog is defined in internal/gateway/middleware/error_codes.go.

Wire Format

All tool calls use the JSON-RPC 2.0 wire format as specified by the Model Context Protocol (MCP).

Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "tavily_search",
    "arguments": {
      "query": "AI security"
    }
  },
  "id": 1
}

Response (success)

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Search results..."
      }
    ]
  },
  "id": 1
}

Response (gateway denial)

{
  "code": "authz_policy_denied",
  "message": "OPA policy denied the request",
  "middleware": "opa_policy",
  "middleware_step": 6,
  "decision_id": "d-abc-123",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Request IDs

The SDK uses an atomic.Int64 counter for JSON-RPC request IDs, starting at 1 and incrementing monotonically per client instance. This ensures unique, sequential IDs that are safe for concurrent use.

Required Headers

Every request sent by the SDK includes the following HTTP headers:

CallModelChat sends additional model-plane headers: X-Model-Provider, X-Residency-Intent, and X-Budget-Profile. See ModelChatRequest.

Retry Behavior

The SDK retries only HTTP 503 Service Unavailable responses. All other error status codes (401, 403, 429, etc.) are returned immediately without retry, since they represent definitive denials.

Backoff Formula

delay = backoffBase * (1 << attempt)

attempt 0:  1s  (backoffBase * 1)
attempt 1:  2s  (backoffBase * 2)
attempt 2:  4s  (backoffBase * 4)

With the default configuration (DefaultMaxRetries=3, DefaultBackoffBase=1s), the SDK will attempt up to 4 total requests (1 initial + 3 retries) over approximately 7 seconds of backoff delay.

Context Cancellation During Backoff

During each backoff wait, the SDK monitors the context for cancellation. If ctx.Done() fires before the backoff timer expires, the SDK returns ctx.Err() immediately (typically context.Canceled or context.DeadlineExceeded).

// Set a 5-second deadline. Will cancel retries if exceeded.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

result, err := client.Call(ctx, "tavily_search", params)
// If the gateway returns 503 repeatedly, err may be context.DeadlineExceeded

Non-retryable Errors

Non-GatewayError failures (network errors, DNS resolution failures, TLS handshake failures) are never retried. These are returned immediately as wrapped fmt.Errorf values.

Advanced Usage

mTLS with WithHTTPClient

In production, agents authenticate to the gateway using mutual TLS (mTLS) backed by SPIFFE SVIDs. Use WithHTTPClient to inject a custom *http.Client with the appropriate TLS configuration.

import (
    "crypto/tls"
    "crypto/x509"
    "net/http"
    "os"

    "github.com/RamXX/agentic_reference_architecture/POC/sdk/go/mcpgateway"
)

// Load SVID certificate and key (provided by SPIRE agent)
cert, err := tls.LoadX509KeyPair("/run/spire/svid.pem", "/run/spire/svid-key.pem")
if err != nil {
    log.Fatal(err)
}

// Load trust bundle (CA certificates)
caCert, err := os.ReadFile("/run/spire/bundle.pem")
if err != nil {
    log.Fatal(err)
}
caPool := x509.NewCertPool()
caPool.AppendCertsFromPEM(caCert)

tlsConfig := &tls.Config{
    Certificates: []tls.Certificate{cert},
    RootCAs:      caPool,
}

httpClient := &http.Client{
    Transport: &http.Transport{TLSClientConfig: tlsConfig},
}

client := mcpgateway.NewClient(
    "https://gateway.precinct.svc:9090",
    "spiffe://agentic-ref-arch.poc/agents/mcp-client/researcher/prod",
    mcpgateway.WithHTTPClient(httpClient),
)

Context Cancellation

All SDK methods accept a context.Context as the first argument. Use context cancellation to bound request duration or cancel in-flight requests during graceful shutdown.

// Cancel all in-flight requests on SIGINT
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
defer cancel()

result, err := client.Call(ctx, "long_running_tool", params)

Goroutine Safety

GatewayClient is safe for concurrent use from multiple goroutines. Request IDs are managed via atomic.Int64, and the underlying *http.Client handles connection pooling. All client state after construction is either immutable or atomic.

client := mcpgateway.NewClient(url, spiffeID)

var wg sync.WaitGroup
for _, tool := range []string{"tool_a", "tool_b", "tool_c"} {
    wg.Add(1)
    go func(t string) {
        defer wg.Done()
        result, err := client.Call(ctx, t, params)
        // handle result/err
    }(tool)
}
wg.Wait()

SPIKE Token Helpers

The Go SDK provides two helper functions for constructing SPIKE token reference strings. These functions produce opaque Bearer tokens that the gateway resolves to real credentials at egress time (middleware layer 13). The format matches the Python SDK's build_spike_token_ref exactly.

BuildSPIKETokenRef

func BuildSPIKETokenRef(spikeRef string, expSeconds int) string

Constructs a Bearer SPIKE token reference string suitable for use as an Authorization header value. If spikeRef is empty, returns an empty string. If expSeconds is <= 0, defaults to 3600 (1 hour).

// Typical usage
ref := mcpgateway.BuildSPIKETokenRef("secrets/groq-api-key", 3600)
// Returns: "Bearer $SPIKE{ref:secrets/groq-api-key,exp:3600}"

// Custom expiration
ref := mcpgateway.BuildSPIKETokenRef("secrets/openai-key", 7200)
// Returns: "Bearer $SPIKE{ref:secrets/openai-key,exp:7200}"

BuildSPIKETokenRefWithScope

func BuildSPIKETokenRefWithScope(spikeRef string, expSeconds int, scope string) string

Like BuildSPIKETokenRef but appends an optional scope qualifier. If scope is empty, the result is identical to BuildSPIKETokenRef.

// With scope
ref := mcpgateway.BuildSPIKETokenRefWithScope("secrets/db-cred", 1800, "read-only")
// Returns: "Bearer $SPIKE{ref:secrets/db-cred,exp:1800,scope:read-only}"

// Without scope (equivalent to BuildSPIKETokenRef)
ref := mcpgateway.BuildSPIKETokenRefWithScope("secrets/key", 3600, "")
// Returns: "Bearer $SPIKE{ref:secrets/key,exp:3600}"

Constants

The package exports three default-value constants used by NewClient when no corresponding option is provided.

const (
    DefaultMaxRetries  = 3
    DefaultBackoffBase = 1 * time.Second
    DefaultTimeout     = 30 * time.Second
)