Skip to main content
Connect to Tilt Agent over the Model Context Protocol (MCP) when your application owns the chat or agent experience. Your application acts as the MCP host and client; Tilt Agent acts as a specialist sub-agent for supported investment workflows. Send a complete outcome to Tilt Agent instead of decomposing it into generic searches or individual construction operations. For example, delegate “Create a quarterly nuclear energy Tilt with 25 constituents and a 10% position cap,” then continue the same Tilt Agent session when the user asks for a change.

Understand the connection

The integration has four separate layers: The remote MCP endpoint is:
Tilt supports two protocol paths:
  • MCP 2026-07-28 uses server/discover and request-scoped transport state.
  • MCP 2025-11-25 compatibility uses initialize and stateless transport.
Use an MCP SDK to negotiate the protocol. Do not use an MCP transport session as Tilt Agent conversation state: conversation continuity comes from the 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:
  1. An unauthenticated MCP request returns 401 Unauthorized. The protected-resource metadata appears in the response’s WWW-Authenticate challenge.
  2. RFC 9728 protected-resource metadata identifies the authorization server, required mcp scope, and exact resource https://tilt.io/mcp/tilt.
  3. Authorization-server metadata advertises the authorization, token, and dynamic client registration endpoints.
  4. The client registers its callback, creates a PKCE verifier and S256 challenge, and sends the user to Tilt to sign in and consent.
  5. The client exchanges the authorization code for a resource-bound access token and sends it as Authorization: Bearer <access_token> on MCP requests.
  6. The client uses the refresh token when the access token expires. Tilt rotates refresh tokens, so store the replacement after every successful refresh.
The standard flow uses a public OAuth client with token endpoint authentication method 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.
Let the MCP SDK follow discovery metadata rather than hard-coding authorization or token endpoints. A custom OAuth implementation must preserve the exact resource through authorization and token exchange, validate callback state, use the registered redirect URI, and store each user’s credentials separately.

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.
Adapt the initialization to the MCP SDK and protocol version your host uses. Configuration file formats are client-specific.

Delegate a complete task

Call delegate_to_agent without session_id for the first turn:
Persist both IDs. 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

Call wait_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.
Return each complete tool result to the orchestrating model. Tilt Agent output uses structured UI elements with descriptive names. A model-driven MCP host can interpret those elements and answer through its own interface. Pass the full result rather than its status-summary text, and do not hard-code a parser for one element type. Carry events across every wait response when your MCP library does not preserve the tool conversation for the model. 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

Reuse session_id for a follow-up after the previous run reaches a terminal status:
Do not restate object IDs merely to recreate continuity. Tilt Agent receives the conversation and linked Tilt context through the durable session. Only one run can be active in a session, so serialize follow-up turns. Creating or refining a Tilt does not publish an index. Publication remains a separate review process.

Handle retries and failures

Delegation can change saved Tilt state and is not idempotent. Do not repeat delegate_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 failed means the delegated turn started but did not complete successfully; inspect its error and events.
Canceling an active run stops further work when possible; it does not roll back changes already completed. Closing a session archives it. Do not close a session after every turn when users may continue the conversation.

Orchestration tools

  • delegate_to_agent starts a run or adds a turn to an existing session. It changes state.
  • wait_for_agent_run waits for new events or a terminal status. It is read-only.
  • get_agent_run reads the complete current run snapshot. It is read-only.
  • get_agent_session reads session context, transcript, and the latest-run summary. It is read-only.
  • cancel_agent_run cancels an active run. It changes state.
  • close_agent_session archives 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 the io.modelcontextprotocol/ui extension and associates delegate_to_agent with this resource:
An MCP Apps-capable host reads the resource through MCP, loads it in the host’s Apps environment, and supplies tool results through the Apps bridge. The app can display run progress and Tilt cards, send follow-up user messages, request app-only tools, and ask the host to open links. Do not treat the 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.