MCP Gateway — Local Prototype

A working, runnable scaffold of the gateway described in ../Notes/MCP Connector - Implementation Plan.md (Phase 1.4) and ../Notes/MCP Connector - Runtime Flow (Okta to BigQuery).md. This is a local testing sandbox, not the real deployment — nothing here is wired into gcp-foundation-artiva or deployed anywhere. Its job is to let the MCP/BigQuery plumbing be built and tested before Artiva's real Okta/WIF credentials exist, and to be a concrete, inspectable answer to "what does the gateway actually look like."

It was built and smoke-tested against the real, currently-installed mcp Python SDK (v2.0.0) — every API used here (MCPServer, TokenVerifier, get_access_token(), streamable_http_app()) was verified against the installed package, not written from memory. A live end-to-end test (ClientSession → initialize → list_tools → call_tool) passed against a running instance of this server before this was handed off.

Architecture note — a refinement found while building this

The earlier Runtime Flow doc described the gateway itself hosting /authorize and /callback and brokering the Okta redirect on Claude's behalf (a "the gateway IS the OAuth server" model). Building against the real SDK surfaced a cleaner, SDK-idiomatic alternative that this prototype uses instead: the gateway acts as a pure MCP Resource Server — it advertises Okta as the external Authorization Server (via AuthSettings(issuer_url=...)), and Claude completes the OAuth login directly against Okta, then sends the resulting Okta token straight through as the bearer token on every call. The gateway never runs /authorize//callback itself; it only verifies whatever token Okta already issued.

This removes an entire layer of custom code (no session store, no redirect-brokering routes) and matches what the current MCP authorization spec is built around. Update (2026-08-21): it turned out this doesn't work against this sandbox's specific Okta org — Claude's connector always requests two scopes (interclient_access, device_sso) that this org treats as permanently mutually exclusive, rejecting the request before any login screen appears. See ../Notes/Claude-Okta Connector Issue - Summary & Path Forward.md for the full investigation.

The broker pattern is now built, as AUTH_MODE=okta_broker (src/oauth_broker.py) — the gateway itself becomes the OAuth authorization server the client talks to, constructing the Okta login request itself (with safe scopes) instead of letting Claude do it. Verified end to end with scripts/manual_broker_test.py: real Dynamic Client Registration, a real interactive Okta login, and a real MCP call with the resulting token — all working. Built directly on the mcp SDK's own OAuthAuthorizationServerProvider interface, not hand-rolled; the BigQuery and WIF-exchange logic (federation.py, bigquery_tools.py) required zero changes, and AUTH_MODE=local/okta are untouched. What's not yet confirmed: whether Claude's own connector completes this flow identically to the test script — that needs a real deployment to test.

Worth updating the Runtime Flow doc's Phase A to match once that's confirmed — flagging here rather than silently changing that doc.

Related MCP server: GCP BigQuery MCP Server

What's implemented vs. deferred

Deployed to Cloud Run (personal sandbox, not Artiva)

terraform/ stands this up in a throwaway free-tier GCP project — see ../Notes/GCP Sandbox/Commands Run - Sandbox Setup.md and ../History/STATUS.md for how that project was set up. terraform plan/apply there creates: the Artifact Registry repo, a dedicated service account, and the Cloud Run service itself (bootstrapped against Google's public placeholder image so the service can exist before a real one is built, then repointed at the real image via gcloud builds submit + another apply).

One non-obvious bug worth knowing if you redeploy this anywhere: mcp.streamable_http_app() has its own host parameter (separate from whatever uvicorn binds to) that defaults to "127.0.0.1" and silently auto-scopes DNS-rebinding Host-header protection to just that address — any real deployment gets a cryptic "Invalid Host header" / HTTP 421 on every request. server.py now passes transport_security explicitly: disabled entirely for AUTH_MODE=local (that mode has no request-level auth of its own anyway — see terraform/cloud_run.tf's public_invoker comment), and properly scoped to PUBLIC_URL's hostname once AUTH_MODE=okta is in play.

Also worth knowing: Cloud Run pins to the exact image string you give it. Pushing a new image over the same tag does not trigger a new revision — Terraform only diffs the string, so it sees no change. Use a new tag (or a fully automated CI pipeline that always does) for every real deploy.

Setup

cd artiva-mcp-gateway-prototype
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Running it today, with zero Artiva inputs (AUTH_MODE=local, the default)

No auth is enforced; every BigQuery call uses your own local credentials instead of the Okta/WIF chain. This tests the MCP wiring and the actual BigQuery query path, independent of anything Artiva hasn't provided yet.

gcloud auth application-default login
# set BQ_PROJECT_ID in .env to a project you can query
python3 run.py
# serves http://127.0.0.1:8080/mcp

Test it without Claude, using the official MCP Inspector (Node-based devtool):

npx @modelcontextprotocol/inspector
# point it at http://127.0.0.1:8080/mcp (Streamable HTTP transport)

Or from Python directly:

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    async with streamable_http_client("http://127.0.0.1:8080/mcp") as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            print(await session.list_tools())
            print(await session.call_tool("query", {"sql": "SELECT 1 AS n"}))

asyncio.run(main())

Running it in real mode (AUTH_MODE=okta)

Needs every value in .env.example's Okta and WIF sections. Two ways to get them:

1. Artiva's real tenant, once the Implementation Plan's Phase 1 "Need from Artiva" inputs land (issuer URL, client ID, groups-claim name, WIF pool/provider IDs).

2. Your own sandbox, sooner — the design doc's own Appendix A evaluation used exactly this approach ("a separate Okta trial tenant and standalone GCP organization") to prove the architecture before touching Artiva's real environment. Same idea: a free Okta developer org + a WIF pool in a personal/test GCP project would let the full Okta → STS → BigQuery chain be exercised end to end before Phase 1 is unblocked.

File map

src/
  config.py          settings, all env-driven
  auth_verifiers.py  OktaTokenVerifier -- verifies a bearer token against Okta's JWKS
  oauth_broker.py    AUTH_MODE=okta_broker -- gateway acts as its own OAuth authorization server
  federation.py       the WIF/STS token exchange (Google's sts.googleapis.com/v1/token)
  bigquery_tools.py  BigQuery client + the three tool implementations
  server.py          wires it all into an MCPServer, exposes the ASGI app
run.py               uvicorn entrypoint
Dockerfile            builds the container Cloud Run runs
terraform/            Artifact Registry + Cloud Run + BigQuery + WIF + IAM for the sandbox deployment

IDE note

If your editor flags the imports as unresolved, point it at .venv/bin/python as the interpreter — it's a local venv, not a global install.