Skip to main content

MCP Tools

The platform integrates with the Model Context Protocol (MCP) to give conversations access to external tools, resources, and prompts. MCP servers are registered on the platform and their capabilities are exposed to the LLM during generation.

Where tools come from​

Three different things can put a tool in front of the model, and they differ in who runs the tool when it is called.

SourceWho executes itYou provide
Platform MCP serversThe platformNothing — they are already there
Client-side toolsYour appThe tool definitions, and the results
Third-party apps via PipedreamPipedreamAn account connection (in progress)

Platform MCP servers​

The platform ships its own MCP servers and exposes them to conversations automatically — covering things like semantic memory, notifications, location enrichment, holiday calendars, and nutrition lookup. You do not register or host anything.

Call mcp-list-available-servers to see what is live for your tenant rather than assuming a fixed set; which servers a given conversation sees also depends on its own MCP configuration and any active agent profile.

Client-side tools​

For anything that has to run on your side — reading device state, navigating your UI, touching a system only your backend can reach — declare it as a client tool in the generation config's client_tools. The model sees it like any other tool, but the platform does not execute it: the call comes back to you, you run it, and you post the result with submit-client-tool-results. See Client-Side Tools below.

This is the extension point. You do not need to stand up an MCP server to give the model your own capabilities.

Third-party apps via Pipedream​

In progress — not available yet

Connecting third-party SaaS apps through Pipedream is under active development and is not exposed on the public API. There are no endpoints to call for it yet.

Until it ships, reach third-party systems with client-side tools — your backend already has the credentials and network access, and the model does not need to know the difference.

Talk to your account team if you want to be told when this lands.

How It Works​

MCP tool execution flow — client sends a message, the LLM requests a tool call, MCP service invokes the MCP server, and the tool result flows back to the LLM before the final assistant message is returned

  1. When a message is sent, the platform includes available tool definitions in the LLM request
  2. If the LLM decides a tool is needed, it returns a tool call request
  3. The platform executes the tool via the MCP service (or asks for approval)
  4. The tool result is fed back to the LLM
  5. The LLM produces its final response incorporating the tool output

Discovering Available Tools​

List MCP Servers​

See which MCP servers are available on the platform:

curl -X POST https://api.travila.ai/api/v1/llm/gateway/mcp-list-available-servers \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{}'

Get Server Info​

Get details about a specific MCP server, including its capabilities:

curl -X POST https://api.travila.ai/api/v1/llm/gateway/mcp-get-server-info \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "memory-server"
  }'

List Tools​

List all tools available from a specific MCP server:

curl -X POST https://api.travila.ai/api/v1/llm/gateway/mcp-list-tools \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "servers": ["memory-server"]
  }'

Returns the tool name, description, and JSON Schema for the input parameters. Omit servers to list tools across every server registered for the conversation.

Calling Tools Directly​

You can call MCP tools directly outside of a conversation:

curl -X POST https://api.travila.ai/api/v1/llm/gateway/mcp-call-tool \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_call": {
      "server_id": "memory-server",
      "name": "search_memories",
      "arguments_json": "{\"query\": \"user preferences\"}"
    },
    "request_id": "req_abc123"
  }'

The call is described by a single tool_call object. arguments_json is a JSON-encoded string, not a nested object. request_id is yours to choose and comes back on the response for correlation.

Tool Approval Flow​

Some tools require explicit user approval before execution. When the LLM requests a tool call that needs approval:

  1. The generation run pauses
  2. The tool call is added to the pending approvals list
  3. The client polls for or is notified of pending approvals
  4. The client submits approvals (approve or deny)
  5. Generation resumes with the approved tool results

Check Pending Approvals​

curl -X POST https://api.travila.ai/api/v1/llm/gateway/list-pending-approvals \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_key": "conv_abc"
  }'

Submit Approvals​

curl -X POST https://api.travila.ai/api/v1/llm/gateway/submit-tool-approvals \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_key": "conv_abc",
    "approvals": [
      {
        "tool_call_id": "call_abc123",
        "approved": true
      }
    ]
  }'

Set approved to false to deny the tool call. The LLM will be informed that the tool was denied and will adjust its response accordingly.

Client-Side Tools​

Some tools are designed to execute on your side (displaying a UI component, navigating to a page, reaching a system only you can reach). The model calls them like any other tool; the platform just hands the call back to you instead of running it.

Declaring them​

Put the definitions in client_tools on the generation config — either as the thread default, or per turn via override_generation_config:

{
  "conversation_key": "conv_abc",
  "default_generation_config": {
    "client_tools": [
      {
        "name": "navigate_to",
        "description": "Navigate the app to a given screen",
        "parameters_json_schema": {
          "type": "object",
          "properties": {
            "screen": { "type": "string", "description": "Screen identifier" }
          },
          "required": ["screen"]
        }
      }
    ]
  }
}

parameters_json_schema is a plain JSON Schema object — it is what the model reads to work out how to call your tool, so describe the fields properly.

The round trip​

  1. The tool call is delivered to the client
  2. The client executes the action locally
  3. The client submits the result back to the platform
curl -X POST https://api.travila.ai/api/v1/llm/gateway/submit-client-tool-results \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_key": "conv_abc",
    "results": [
      {
        "tool_call_id": "call_xyz789",
        "result_json": "{\"navigated_to\": \"/settings\"}"
      }
    ]
  }'

Resources​

MCP servers can also expose resources — structured data that the LLM can reference.

List Resources​

curl -X POST https://api.travila.ai/api/v1/llm/gateway/mcp-list-resources \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "memory-server"
  }'

Read a Resource​

curl -X POST https://api.travila.ai/api/v1/llm/gateway/mcp-read-resource \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "memory-server",
    "uri": "memory://user/preferences"
  }'

Prompts​

MCP servers can expose reusable prompt templates.

List Prompts​

curl -X POST https://api.travila.ai/api/v1/llm/gateway/mcp-list-prompts \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "memory-server"
  }'

Get a Prompt​

curl -X POST https://api.travila.ai/api/v1/llm/gateway/mcp-get-prompt \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "memory-server",
    "name": "summarize_history"
  }'