PRECINCT SDKs

First-class SDK support in Python and Go for integrating agents with the PRECINCT gateway. Both SDKs handle SPIFFE identity injection, structured error mapping, and gateway communication automatically.

First Time Integrating?

The Integration Guide walks through identity registration, tool setup, and policy configuration before you start using the SDK.

Overview

PRECINCT provides two official SDKs that mirror each other's semantics across languages. Both SDKs wrap the gateway's JSON-RPC API and provide idiomatic interfaces for tool invocation, error handling, and identity management.

Roadmap: Rust, TypeScript, and Elixir SDKs are planned. Follow the GitHub repository for updates.

Python SDK: mcp_gateway_sdk

Async-first Python client built on httpx. Includes typed error hierarchy, runtime helpers for PydanticAI/DSPy/LangGraph, and OpenTelemetry integration.

  • Python ≥3.10
  • Automatic SPIFFE ID injection
  • Exponential backoff retry (503 only)
  • Context manager lifecycle

Full Python SDK Reference →

Go SDK: mcpgateway

Idiomatic Go client with functional options, context-based cancellation, and zero external dependencies beyond google/uuid.

  • Go ≥1.24.6
  • Auto-detects protocol methods vs tool names
  • Goroutine-safe with connection pooling
  • mTLS via custom http.Client
  • SPIKE token helpers: BuildSPIKETokenRef, BuildSPIKETokenRefWithScope

Full Go SDK Reference →

Error Code Mapping

Both SDKs map the gateway's structured deny codes to language-specific error types. This table shows the correspondence.

SDK error type mapping for gateway deny codes
Gateway Code Layer Python Exception Go Error Type
spiffe_auth_required 3 AuthenticationError *AuthenticationError
tool_not_in_registry 5 ToolNotFoundError *ToolNotFoundError
tool_hash_mismatch 5 ToolIntegrityError *ToolIntegrityError
authz_policy_denied 6 AuthzDeniedError *AuthzDeniedError
dlp_credentials_detected 7 DLPViolationError *DLPViolationError
stepup_required 9 StepUpRequiredError *StepUpRequiredError
rate_limit_exceeded 11 RateLimitError *RateLimitError
circuit_breaker_open 12 CircuitBreakerError *CircuitBreakerError

Automatic SPIFFE Identity

Both SDKs can automatically obtain SPIFFE identity from the local SPIRE agent when running inside a PRECINCT-managed environment. This eliminates the need to manually specify a SPIFFE ID.

Python Auto-discovery

# When running inside PRECINCT, the SDK discovers the SVID automatically
# via the Workload API Unix Domain Socket
client = GatewayClient(
    gateway_url="http://localhost:9090",
    # No spiffe_id needed: discovered from SPIRE agent
)

Go Auto-discovery

// Auto-discover SPIFFE identity from local SPIRE agent
client, err := mcpgateway.NewClient(
    "http://localhost:9090",
    mcpgateway.WithAutoSPIFFE(),  // Connects to SPIRE agent UDS
)
Development Mode

In development (Docker Compose with make up), you can manually set the SPIFFE ID via the constructor parameter. In production (Kubernetes), use auto-discovery to obtain identity from the local SPIRE agent.

Installation

Python

pip install mcp-gateway-sdk

See the Python SDK installation guide for optional dependency groups.

Go

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

See the Go SDK installation guide for local development setup.

Version Note

Both SDKs are part of the PRECINCT proof-of-concept and are versioned alongside the main repository. For production use, pin to a specific commit or tag.