MCP Streamable HTTP

When to use it

Choose Streamable HTTP when the client already speaks MCP but cannot—or should not—start a local Kavach process. It is the native remote MCP interface, not a Swagger or ordinary REST endpoint.

Start streamable-http MCP Service

uv run kavach-mcp --transport streamable-http --host 127.0.0.1 --port 8002

The endpoint and operational probes are:

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

Authentication

In Keycloak mode, every MCP request needs an access token. Kavach 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

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

headers = {"Authorization": "Bearer <access-token>"}

async with streamablehttp_client("http://127.0.0.1:8002/mcp", headers=headers) as streams:
    read_stream, write_stream, _get_session_id = streams
    async with ClientSession(read_stream, write_stream) as session:
        await session.initialize()
        result = await session.call_tool(
            "context.current",
            {"context": {"organization_id": "org_default", "project_id": "project_default"}},
        )

The context object selects the organization and project. It does not establish identity or bypass authorization.

MCP Inspector

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

./kavach-local.sh
# In another terminal:
uv run kavach-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 at /mcp: missing, expired, or invalid bearer token.
• A tool result derived from 403: token is valid but membership, scope, role, or permission is missing.
• OPTIONS /mcp 200: Inspector CORS preflight accepted.
• Terminating session: None: expected stateless-transport behavior.

For conventional HTTP clients and Swagger UI, use MCPO.