MCP Streamable HTTP

What this endpoint is for

Use Streamable HTTP when your client already understands the Model Context Protocol (MCP). This is the recommended endpoint for VS Code, desktop AI clients, and other AI-agent tools that connect over HTTP.

MCP is a tool protocol: the client first asks AI Governance Platform which tools exist, then calls a named tool with JSON input. It is not a normal REST or Swagger endpoint. If your application needs ordinary HTTP routes, an OpenAPI document, or generated SDKs, use MCPO on port 8001 instead.

Stateless protocol behavior

This endpoint prefers MCP 2026-07-28. A tool request is self-contained: it includes the protocol version, client metadata, and routing headers. There is noinitialize exchange or Mcp-Session-Id, so a later request can reach any healthy server instance behind a normal load balancer.

This does not make AI Governance Platform's application state temporary. Governance decisions, audit records, jobs, replays, and assets are durable resources. When a tool needs continuity, pass the relevant explicit resource ID in its arguments. The endpoint retains legacy session-based Streamable HTTP support for existing clients, but new integrations should use 2026-07-28.

This follows the MCP 2026-07-28 specification release, which introduced stateless requests, header-based routing, cache hints, and multi-round request support.

Start and check the service

When using the Docker Compose development stack, the service starts asai-governance-mcp-http and listens on port 8002. Start the complete local stack from the AI Governance Platform repository:

./servers.sh

For a local Python process instead of Compose, start the endpoint with:

uv run ai-governance-mcp --transport streamable-http --host 127.0.0.1 --port 8002

Before configuring a client, check that the process is alive:

curl http://localhost:8002/health
# Expected: {"status":"ok"}

The useful local URLs are:

MCP endpoint: http://localhost:8002/mcp
Health:       http://localhost:8002/health
Readiness:    http://localhost:8002/ready

Connect VS Code

VS Code connects as a human user through Keycloak. It opens a browser the first time you connect, then stores the short-lived OAuth token securely. Do not put a password, a client secret, or a copied bearer token inmcp.json.

Create or open .vscode/mcp.json and add the following server. The clientIdtells VS Code to use AI Governance Platform's preconfigured public PKCE client instead of attempting dynamic client registration.

{
  "servers": {
    "ai-governance": {
      "type": "http",
      "url": "http://localhost:8002/mcp",
      "oauth": {
        "clientId": "ai-governance-mcp-vscode"
      }
    }
  }
}

1. Run MCP: List Servers from the VS Code Command Palette.
2. Select ai-governance, then choose Start or Connect.
3. When Keycloak opens in your browser, sign in with the local AI Governance Platform user studio.
4. Use the value of AI_GOVERNANCE_STUDIO_PASSWORD in keycloak-postgres/.env.keycloak as the local password.
5. Let the browser return to the local callback URL. VS Code then discovers the tool list automatically.

Understand tool names and context

Core AI Governance Platform code uses dotted names internally, such ascontext.current. Native Streamable HTTP publishes portable MCP names with underscores because clients such as VS Code reject dots. The server converts the name back before it runs the existing handler.

Internal / stdio name       Native HTTP name for VS Code
context.current             context_current
provider.list               provider_list
evaluation.get              evaluation_get
project.create              project_create

Start with a read-only tool. In Copilot Chat, ask for the exact tool name and say not to use a write tool:

Call exactly one MCP tool: provider_list.
Do not call any write tool.
Use an empty JSON object: {}

Most organization-scoped tools need a context. Context chooses the organization and project to work in; it never grants access or impersonates a user. The signed-in user still needs membership and the required role.

{
  "context": {
    "organization_id": "org_default",
    "project_id": "project_default"
  }
}

Authentication

In Keycloak mode, every MCP request needs an access token. AI Governance Platform validates the token at the HTTP boundary and forwards the same credential to the REST control plane. The token sub is the actor used for audit, membership, and permission checks.

Authorization: Bearer <access-token>

For a local smoke test, run uv run python scripts/mcp/fetch-access-token.py. It copies a short-lived local service-account token to the clipboard without printing it. User-facing clients should use the signed-in user's OIDC token; unattended clients should use their own dedicated workload identity.

Example

This local smoke test makes one stateless tools/call request. It has no prior handshake and does not reuse a session identifier.

( unset VIRTUAL_ENV; uv run python scripts/mcp/fetch-access-token.py )
TOKEN="$(pbpaste)"

curl -sS http://127.0.0.1:8002/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: provider_list' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "provider_list",
      "arguments": {},
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": {
          "name": "manual-curl-test",
          "version": "1.0"
        },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }' | jq '{isError: .result.isError, status: .result.structuredContent.status}'

Expected output is {"isError": false, "status": "ok"}. Thepbpaste step is for macOS; on another platform, set TOKEN from your secure token source. For a real client, send the same protocol metadata on every request rather than copying this curl invocation verbatim.

MCP Inspector

Use the official Inspector for a development-only browser UI. Start the local stack, native MCP service, and then the helper below:

./servers-local.sh
# In another terminal:
uv run ai-governance-mcp --transport streamable-http --host 127.0.0.1 --port 8002
# In a third terminal:
./scripts/mcp/start-inspector.sh

Open the complete URL printed by Inspector, including itsMCP_PROXY_AUTH_TOKEN query parameter. In the UI choose Streamable HTTP and Direct, use the MCP URL above, enable a customAuthorization header, and paste Bearer <token>. Leave its OAuth fields empty for this local token-header workflow.

Troubleshooting

• 401 missing_authorization: the client reached AI Governance Platform without a token. Reconnect the server and complete the browser sign-in; do not add a Keycloak password to the MCP configuration.
• VS Code says the OAuth request was canceled: run Authentication: Remove Dynamic Authentication Providers, then stop and start the AI Governance Platform MCP server from MCP: List Servers. This clears a stale local OAuth registration without changing server data.
• VS Code shows old dotted tool names or cannot find an underscore tool: stop and start the server, or remove and add the MCP server again. VS Code can cache a tool list after a server update.
• Invalid scopes: openid profile email: start AI Governance Platform through ./servers.sh. Startup reconciles the local Keycloak client even when an old Keycloak volume already exists.
• A tool result derived from 403: authentication succeeded, but the signed-in user lacks a membership, project scope, role, or permission for that request.
• OPTIONS /mcp 200: Inspector CORS preflight accepted.
• Terminating session: None: expected stateless-transport behavior.

For conventional HTTP clients and Swagger UI, use MCPO.