Understand the connection
The integration has four separate layers:
The remote MCP endpoint is:
- MCP
2026-07-28usesserver/discoverand request-scoped transport state. - MCP
2025-11-25compatibility usesinitializeand stateless transport.
session_id returned by delegate_to_agent.
The server exposes tools and resources. It does not expose an MCP prompt
catalog.
Authorize the user
Tilt uses OAuth 2.0 authorization code flow with S256 PKCE. A capable MCP client can discover the authorization flow from the endpoint:- An unauthenticated MCP request returns
401 Unauthorized. The protected-resource metadata appears in the response’sWWW-Authenticatechallenge. - RFC 9728 protected-resource metadata
identifies the authorization server, required
mcpscope, and exact resourcehttps://tilt.io/mcp/tilt. - Authorization-server metadata advertises the authorization, token, and dynamic client registration endpoints.
- The client registers its callback, creates a PKCE verifier and S256 challenge, and sends the user to Tilt to sign in and consent.
- The client exchanges the authorization code for a resource-bound access
token and sends it as
Authorization: Bearer <access_token>on MCP requests. - The client uses the refresh token when the access token expires. Tilt rotates refresh tokens, so store the replacement after every successful refresh.
none. Public clients have no client secret, but the MCP endpoint still
requires an access token.
The standard external OAuth connection currently runs in the authorized
user’s personal Tilt organization. Naming another organization in a prompt
or context reference does not change the connection’s authorization. Each
end user authorizes their own Tilt account.
Connect with an MCP client
The following TypeScript example uses the MCP SDK’s Streamable HTTP transport after OAuth has supplied an access token. Keep token acquisition and refresh in your OAuth provider rather than embedding a token in source code.Delegate a complete task
Calldelegate_to_agent without session_id for the first turn:
runId identifies this turn; sessionId identifies the
durable Tilt Agent conversation. Map the session to the same authorized user
and conversation in your application.
delegate_to_agent accepts the task and returns before Tilt Agent finishes.
The initial result can report queued, starting, or running. Receiving
the tool result does not mean the task succeeded.
Wait for progress and consume the result
Callwait_for_agent_run until it returns a terminal status: succeeded,
failed, or canceled. Each call can wait for up to 30 seconds. Carry
last_event_id into the next call as after_event_id so that the server only
returns newer events.
get_agent_run returns the complete event
history when a client reconnects or loses its cursor.
Choose how to present output
Choose between two presentation options:Let the MCP host interpret it
A model-driven host can receive the complete structured result from the run tools. The model interprets Tilt’s messages, cards, tables, and other UI elements, then responds through the host’s native interface.Use Tilt’s MCP App
An MCP Apps-capable host can render Tilt’s complete interactive experience without mapping UI elements itself. Use the app to show Tilt cards, progress, and follow-up interactions. Tilt can also customize the MCP App experience for a third-party integration.Tilt is exploring additional custom rendering options. Contact Tilt to
discuss a specific integration.
Continue the same Tilt Agent session
Reusesession_id for a follow-up after the previous run reaches a terminal
status:
Handle retries and failures
Delegation can change saved Tilt state and is not idempotent. Do not repeatdelegate_to_agent after an ambiguous timeout. If you received the run
ID, inspect the existing run with get_agent_run before deciding what to do
next.
Handle three failure layers separately:
- HTTP or OAuth failures mean the connection or token could not authorize the request.
- JSON-RPC or tool errors do not prove that no state changed. Inspect any known run or session before retrying the call.
- A retrieved run with status
failedmeans the delegated turn started but did not complete successfully; inspect its error and events.
Orchestration tools
delegate_to_agentstarts a run or adds a turn to an existing session. It changes state.wait_for_agent_runwaits for new events or a terminal status. It is read-only.get_agent_runreads the complete current run snapshot. It is read-only.get_agent_sessionreads session context, transcript, and the latest-run summary. It is read-only.cancel_agent_runcancels an active run. It changes state.close_agent_sessionarchives a session. It changes state.
Host Tilt’s MCP App
MCP Apps is an optional presentation layer on the same authenticated MCP connection. Tilt advertises theio.modelcontextprotocol/ui extension and
associates delegate_to_agent with this resource:
ui:// URI as a public web URL or load it directly in a
general iframe. Follow the MCP Apps host
documentation, enforce
the resource’s security metadata, and hide app-only tools from the model.
Core MCP and MCP Apps support are separate host capabilities. If a host does
not support MCP Apps, let its model interpret the complete structured run-tool
output. Use the terminal run status to determine whether the delegation
succeeded.