Tembo MCP

The Model Context Protocol interface to the full Tembo public API, generated from the same OpenAPI contract that drives the SDK. There are no handwritten endpoint tools or SDK-method mappings to maintain.

One package, one generated catalog, two standard transports:

• Hosted Streamable HTTP: native Clerk OAuth or a Tembo API key in Authorization: Bearer <key>, with organization-scoped public API permissions. Trusted services can also use the existing agent bearer secret with an explicit organization (see below).
• Local stdio: the same tools through @tembo-io/mcp, using your API key. Read-only unless you pass --allow-writes.

Both transports use the official MCP TypeScript SDK v2 serving entries and support the 2026-07-28 protocol plus legacy clients using the 2025-11-25 handshake. The old five-tool implementation is replaced, not maintained as a separate server.

Full API access

By default, each generated API operation is exposed directly as an MCP tool. This lets clients use their native tool discovery and search behavior without an extra MCP-specific search layer.

Set MCP_TOOL_MODE=compact to expose a four-tool compatibility interface instead:

Tool	Purpose
search_tools	Search all generated operations by keyword, method, or path; paginate with offset and limit
get_tool_schema	Retrieve an operation's exact name, input schema, method, path, and safety annotations
call_read_tool	Execute a discovered read-only operation
call_write_tool	Execute a discovered mutating operation after write authorization

For example, search for sessions, inspect a returned operation with get_tool_schema, then supply its exact name and arguments to the appropriate call tool. The server rejects unknown operation names, invalid arguments, and attempts to send a mutation through the read tool. It is not an arbitrary-URL HTTP proxy or a code-execution sandbox.

tools/list paginates direct tools at 50 operations. Both modes reach the same public operations and enforce the same permissions. Tool results include structured { "data": ... } output and a text representation for compatible clients; annotations are hints, not authorization rules.

Live session output

WebSocket handshakes are resources, not request/response tools. When the schema exposes /v1/live, subscribe to tembo://sessions/{sessionId}/events: subscriptions/listen with resourceSubscriptions on the 2026-07-28 protocol, or resources/subscribe on legacy stdio. The server obtains a ticket using the caller's credentials, waits for subscription-level authorization of sessions.events, and sends notifications/resources/updated for output deltas and reconnects.

Read the resource after updates. Its JSON contains recorded (the latest REST event page) and live (cursor, deltas, truncated, gap). Each live delta has its own cursor and { type: 'delta', data: { event, message, ... } } payload. The buffer makes actual provider output available before REST persistence; process cursors newer than the last one you read. It holds at most 100 deltas and 256 KiB per active credential/session scope. truncated or gap signals that readers must reconcile recorded events; this is not a durable replay stream. REST authorization is checked before returning any buffered content. Buffers are isolated by credentials and released when the last subscription ends.

Fresh tickets and subscriptions are used on reconnect. Scoped refusals terminate the listen, including stdio. At most 10 session resource URIs are allowed per listen. Legacy HTTP is stateless and cannot receive updates; it can still read recorded events. The bundled production schema exposes /v1/live, so the server serves the events resource. Schemas without /v1/live fall back to the earlier tembo://sessions/{sessionId}/messages resource and watcher.

Dev live smoke test

Set TEMBO_API_KEY and TEMBO_TEST_SESSION_ID, then run npx tsx --test tests/dev-live.test.ts (it is skipped otherwise, including in npm test). It tests HTTP and stdio with the dev public schema, stored temporarily rather than replacing the production snapshot. TEMBO_API_URL defaults to https://internal.tembo-development.com/public-api for this test only; MCP_OPENAPI_PATH can supply another schema. Add RUN_AGENT=1 to send a minimal prompt through the generated MCP tool, verify actual streamed tokens through resource reads, and stop the session afterward. Agent mode grants stdio writes for this test and incurs usage charges; use a dedicated test session.

Add FORCE_RECONNECT=1 in agent mode to disconnect the upstream socket after the first completed turn, verify the stream gap/reconnect notification, and stream a second turn on both transports. The reconnect hook is loaded only by this test, never by the normal server.

The normal server and schema-update script still default to production. Explicit TEMBO_OPENAPI_URL and TEMBO_API_URL overrides allow a reviewed schema refresh for another environment; npm run update:openapi replaces the tracked snapshot, so do not use it merely to test dev.

Run from source

Requires Node.js 22 or newer.

npm ci
npm run build
node dist/index.js --help

Local stdio

Create an API key in Tembo, then configure your MCP client to launch the built CLI:

{
  "mcpServers": {
    "tembo": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/dist/index.js"],
      "env": {
        "TEMBO_API_KEY": "your-api-key"
      }
    }
  }
}

For local writes, add --allow-writes to args. The API key's server-side permissions still apply. Store the key in your client's secret mechanism where available, not in a committed configuration file. The CLI does not require Clerk settings in stdio mode and reserves stdout for protocol messages.

The package name remains @tembo-io/mcp and the executable remains tembo-mcp. After version 0.2.0 is published, npx -y @tembo-io/mcp@0.2.0 launches this implementation. This PR does not publish that version; the existing registry release must not be mistaken for this code.

Hosted HTTP with Clerk

cp .env.example .env
# Configure the canonical MCP URL, Clerk issuer, and API root.
npm run dev

For production, inject the environment and run npm start or the container. Configure clients with your deployed /mcp URL; the initial 401 response points them to public OAuth protected-resource metadata and requests the organization-selection scope.

Clerk handles client registration, login, consent, and refresh. Clerk must issue JWT OAuth access tokens with the audience claim enabled. The companion API uses the Clerk SDK to verify the token signature, issuer, expiry, and exact environment-specific MCP audience, resolves the selected organization through Clerk userinfo, and checks current membership. Configure MCP_OAUTH_ISSUER with the Clerk issuer; the Tembo API selects the trusted SaaS MCP audience from its deployment environment. The hosted MCP process never stores a shared API key or Clerk secret. There are no custom registration, authorization, or token endpoints here.

Deployment requires the companion API OAuth changes. Configure that API with:

MCP_OAUTH_ISSUER=https://your-instance.clerk.accounts.dev

The API reuses its existing CLERK_SECRET_KEY. Both services must use the same Clerk instance. There is no MCP client-ID allowlist; Clerk manages client registration and user consent. Leaving the API's issuer unset disables OAuth access.

In Clerk, enable Organizations, require PKCE, and configure default OAuth scopes to include user:org:read for organization selection. Enable native Dynamic Client Registration for clients that require it, so users can connect using only the MCP URL. Keep consent enabled. DCR exposes a public registration endpoint: monitor registered clients and understand that client names are not proof of trust. Prefer Clerk's CIMD support for compatible clients where available. See Clerk's guide: https://clerk.com/docs/guides/ai/mcp/connect-mcp-client.

Hosted OAuth grants full public API access within the selected organization, subject to existing user permissions. This includes writes, credential creation, billing changes, deletion, and agent execution. Make that clear during onboarding and consent. There are no custom tembo:* scopes or read-to-write step-up flow. MCP tool approval remains the client's responsibility. No tool automatically retries a failed mutation.

Configuration

Variable	Applies to	Default / meaning
TEMBO_API_URL	Both	https://api.tembo.io; local deployments must include the API prefix and /public-api
MCP_TOOL_MODE	Both	all; use compact for the four-tool compatibility interface
MCP_OPENAPI_PATH	Both	Optional local JSON file for development/self-hosting; defaults to the bundled snapshot
TEMBO_API_KEY	Stdio	Required; forwarded only to the configured API
MCP_PUBLIC_URL	HTTP	Required canonical HTTPS URL ending exactly in /mcp; HTTP allowed on loopback
MCP_OAUTH_ISSUER	HTTP	Optional Clerk HTTPS issuer origin; unset or empty disables OAuth, not bearer API-key/agent auth
MCP_ALLOW_INSECURE_HTTP	HTTP	false; permits an explicitly configured non-loopback HTTP MCP_PUBLIC_URL only when OAuth is disabled
MCP_ALLOWED_ORIGINS	HTTP	Optional comma-separated browser origins, in addition to the server's own origin
HOST	HTTP	127.0.0.1; container sets 0.0.0.0
PORT	HTTP	3000

--transport stdio is the CLI default. --transport http starts the hosted server. --allow-writes is only valid for stdio; HTTP access comes from the caller's Clerk OAuth grant or API key and existing API permissions.

For Tembo's gateway/code mode, add an HTTP connection using existing static-header credentials: Authorization: Bearer <organization-api-key>. No interactive login is needed. Store the key in the connection's secret storage, not in source or tool arguments. The API verifies the key on every request, including revocation, and derives the organization from its key record. Existing internal MCP tools remain separate.

Trusted Tembo services may instead send Authorization: Bearer <existing-agent-secret> together with X-Agent-Org-Id: <organization-id>. The API reuses authAgent, requires a known organization, and retains its organization-scoped database client. The MCP forwards the verified organization only for agent identities. This is privileged service authentication: the shared secret holder can select any known organization. Keep it in trusted backend secret storage, never customer MCP configs, model-visible tool arguments, or untrusted agent sandboxes. Organization-scoped API keys remain the safer choice there. Session tokens are not supported. This adds support only; it does not migrate existing agent connections.

docker build -t tembo-mcp .
docker run --rm --env-file .env -p 3000:3000 tembo-mcp

Self-hosted without Clerk

Run the same HTTP server with MCP_PUBLIC_URL pointing to its canonical /mcp endpoint and TEMBO_API_URL pointing to your own API, including /public-api (and any API prefix). Leave MCP_OAUTH_ISSUER unset or empty. No Clerk account, Clerk secret, OAuth registration, or login is required. The API must include the companion auth-context changes.

HTTPS is recommended. For a private-network installation that intentionally terminates plain HTTP at the MCP process, set MCP_ALLOW_INSECURE_HTTP=true. This opt-in applies only to the public MCP URL and is rejected when OAuth is enabled.

Clients authenticate using an API key, or trusted backend services use the existing agent secret plus X-Agent-Org-Id. Every request is still authenticated by your API. Without an issuer, OAuth discovery endpoints are absent and authentication errors advertise bearer credentials, not a Clerk login. Configuring an issuer enables OAuth alongside those credential types; configure the API with the same issuer and its matching Clerk secret.

This supports a later migration of public-API-backed agent tools; it does not replace internal-only tools or automatically change existing agent connections.

OpenAPI lifecycle

At startup the server reads the versioned openapi/openapi.json bundled in npm and Docker releases, without fetching a live schema. A maintained OpenAPI converter supplies operation metadata and request schemas; name abbreviation is disabled so operation names remain descriptive. Tool names are generated from OpenAPI operation IDs in lowercase kebab case (for example, list-sessions) and validated against the MCP tool-name grammar. Rename an operation in the OpenAPI contract rather than adding a handwritten MCP alias. The official MCP SDK supplies the protocol implementation. A shared adapter normalizes composed object schemas, validates arguments, and dispatches to the generated API client. No per-endpoint adapter is needed.

Startup checks that all public operations generate unique tools, except WebSocket handshakes (operations with a 101 response), which are served as resources, and operations the JSON executor cannot serve: non-JSON request bodies such as file uploads, and redirect-only responses such as file downloads (currently the profile picture upload and download). npm run update:openapi fetches the canonical public contract and validates coverage and schemas before updating the snapshot. There are no deployment-dispatch or daily update workflows: after a production API release, run the command manually and open a review PR. Unchanged schemas produce no diff. Merge the reviewed snapshot, then release/redeploy MCP; restarting an old release does not change its tools. SDK releases are independent.

The removed schema-update workflows no longer require their CI GitHub App credentials; do not remove shared credentials still used by other workflows. npm publication remains separate.

The coverage check currently validates 149 public operations against generation and schema compilation. It does not call authenticated customer endpoints or prove that every possible request encoding works. New content types and unusual schemas need serialization regression tests. Internal routes and the existing sandbox-only MCP endpoint are not part of this public contract.

The sync script omits ISO timestamp defaults from response definitions: the public schema evaluates some generated date defaults at fetch time, which otherwise creates a diff on every refresh. Request defaults and actual API responses are unchanged.

Development and checks

npm run typecheck
npm test
npm run check:coverage
npm run build
npm pack --dry-run
npm audit

Tests cover current and legacy HTTP/stdio clients, generated CRUD, composed schemas, compact discovery, scope challenges, argument validation, caller isolation, and offline schema loading. CI checks the committed snapshot, not a changing production schema. The schema-update command fetches the deployed contract; it never calls customer operations.

Image publishing and deployment

The Publish MCP image workflow runs manually on main or when a GitHub release is published. It requires the source commit to be on main, runs tests, typecheck, schema coverage, and dependency audit, then publishes a Linux amd64 image to the shared ECR repository tembo-mcp. The image tag is the full 40-character MCP commit SHA, not the monorepo commit or a mutable latest tag. Rerunning a publication reuses the existing immutable image. The workflow summary records its tag and digest. Publishing does not deploy anything or publish npm.

Before publishing, configure the release GitHub environment in this repo:

• Set ECR_REPO_PREFIX to the shared registry host and ECR_ROLE_ARN to the existing iam-role/ecr-access role ARN, as repository or environment variables.
• Have infra create tembo-mcp in the shared registry in us-east-1, with immutable SHA tags and mutable *.mcp environment tags, matching the existing ECR pattern.
• Add repo:tembo/mcp:environment:release to the existing ECR role's GitHub OIDC trust. This reuses its shared registry permissions, including tembo-mcp, without ECS deployment permissions. No new role or long-lived AWS credentials are needed.
• Protect the release environment with approved branch/tag rules and required reviewers. The separate check job runs without AWS credentials.

The monorepo's manual Deploy MCP workflow accepts environment (dev, staging, or prod) and the image SHA. It reuses deploy-ecs.yaml, including its rollout/stability checks and environment tagging. It uses the existing monorepo environment roles/registry variables and maps dev to the test GitHub environment, staging to staging, and prod to production. Production approval is controlled by that existing GitHub environment; verify its required-reviewer policy before launch. Deployments run only from monorepo main and serialize per environment. The same image can be promoted without rebuilding; rollback selects a previous published SHA.

Infra must provision the following contract before running deployment (no resources are created by these workflows):

Resource	Expected value
ECS clusters	tembo-use1-{dev,staging,prod}-api
Service and task-definition family	tembo-use1-{dev,staging,prod}-mcp
Container name	tembo-mcp
Container port / health path	3000 / /health
Runtime environment	MCP_PUBLIC_URL, MCP_OAUTH_ISSUER, TEMBO_API_URL; image defaults HOST=0.0.0.0
Public routing	Host routing to both /mcp and /.well-known/oauth-protected-resource*; production vanity domain mcp.tembo.io

Use each environment's own API URL and Clerk issuer. The MCP container needs no Clerk secret, database credentials, or shared API key. Ensure the task execution role can pull the shared ECR image and deploy/tagging roles can access the new service/repository. Configure TLS, rate limits, logs, and streaming timeouts in infra. Create registry/IAM first, publish an initial image, then provision services using that image and promote through dev, staging, and production.

Schema review and deployment are intentionally separate: API deploy → schema PR → review/merge → publish image → deploy that SHA. No schema-update event can automatically deploy production.

Rollout boundary

The code is the main implementation, not a parallel preview. Merging it does not deploy a host, publish npm, or configure Clerk. Before enabling production, test real client login, org selection, consent denial, refresh, cross-org access, membership removal, and revocation. The API checks Clerk's current grant and organization membership on each request.

Deploy behind HTTPS and edge rate limits. Review upstream redirect policy and egress restrictions, and monitor provider failures without logging credentials or payloads. See SECURITY.md.