1. Docs
  2. Actions
  3. Templates

MCP server

Last updated Open markdown version

Model Context Protocol (MCP) is a standard protocol for LLMs to connect to external services and interact with them. You can build custom remote MCP servers directly from the Tines storyboard.

To get started, search for "MCP" in the Templates section on the left panel, and drag your first MCP server to the storyboard. After configuring it with some tools, you can reference the server URL and authentication parameters from your MCP client to try it out.

Adding tools

MCP servers support template, send-to-story and custom tools. They can can be configured in the same way as the AI Agent action. They will be exposed directly via the server and available for invocation from your client. Tool names, descriptions and arguments are automatically available on your MCP client after successful connection.

Access control

There are four access control modes for MCP servers:

  • Anyone with the path (public)

  • Anyone with the secret (passed in via the URL or HTTP Authorization)

  • With a Tines API Key

    • Members of specified teams

    • Any member of the Tines tenant

  • With OAuth

    • Members of specified teams

    • Any member of the Tines tenant

You can read more about these here.

Configuring your MCP client

An MCP server created in Tines can be used directly by any client that supports the Streamable HTTP protocol for remote MCP servers. Typically, you can use an MCP setting like this on a client that supports this syntax.

{
  "mcpServers": {
    "tines": {
      "url": "https://<tenant>.tines.com/mcp/<mcp-path>",
      "headers": {
        "Authorization": "Bearer <webhook-secret or api-key>"
      }
    }
  }
}

Additionally, if you are using a client that only support local servers (stdio), you can use mcp-remote to act as a local proxy. To do this, you need Node.js installed locally and the following MCP settings:

{
  "mcpServers": {
    "tines": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<tenant>.tines.com/mcp/<mcp-path>",
        "--header",
        "Authorization:${AUTH_HEADER}",
        "--transport",
        "http-only"
      ],
      "env": {
        "AUTH_HEADER": "Basic <webhook-secret or api-key>"
      }
    }
  }
}

Protocol details

  • Only Streamable HTTP is supported (no SSE or stdio). See above for information about using a mcp-remote as an adaptor

  • Authentication can be done via the HTTP Authorization header or via the URL (when using secrets)

  • The supported MCP protocol version is2025-06-18

    • Version 2025-03-26 has partial support, and should work on the majority of clients that support it.

    • Version 2024-11-05 is not supported

  • Only tools are supported. Tool responses are always text.

Unsupported features

  • Prompts

  • Resources

  • OAuth

  • Notifications

  • Sessions

  • Pagination

  • JSON-RPC Batching (only relevant for spec 2025-03-26)

Limits

The MCP server implementation is subject to the same limits that apply to response-enabled webhooks. That is:

  • Tool response time cannot exceed 30 seconds.

    • After this time your client will receive a timeout error.

    • When this happens, the tool can continue to run in the background, but the result does not reach the client.

  • You cannot have more than 100 (1000 in dedicated tenants) concurrent tool/call requests.

    • These are counted globally across all MCP servers and response-enabled webhooks in your tenant.

  • Tool execution happens asynchronously and is subject to the same fair orchestration system that applies to all stories.

Emitted events

The MCP server will emit events for the requests it gets. These are:

  • initialize

  • tools/list

  • tools/call

In the case of the tools/call emitted event, the tool result is not included in the event. However, each tool call will be available on the tool itself, which emits an event upon completion.

To avoid unnecessary noise, methods that do not provide meaningful information (such as notifications or ping) will not result in downstream events.

When a request is authenticated with a Tines API key or OAuth, the authenticated user's email is available in the emitted event at <<headers.email>>, and in linked tool actions at META.headers.email. See Request headers in tools and events for details.

Request headers in tools and events

When Include headers is enabled on your MCP server (the default), Tines captures the incoming HTTP request headers from each MCP client request. You can use these headers in two places:

  • In downstream actions connected to the MCP server — reference <<headers.*>> from the emitted event (for example, <<headers.email>>).

  • In tool actions linked to the MCP server — reference META.headers.* in formulas (for example, <<META.headers.email>>).

Headers reflect the MCP request that triggered the current tool call. If a client sends custom headers in its MCP configuration, those headers are available too:

{
  "mcpServers": {
    "tines": {
      "url": "https://<tenant>.tines.com/mcp/<mcp-path>",
      "headers": {
        "Authorization": "Bearer <webhook-secret or api-key>",
        "X-Department": "security"
      }
    }
  }
}

In a tool action, META.headers.x_department would return security.

Header names

Header names follow the same rules as webhooks:

Authenticated requests

When a request is authenticated with a Tines API key or OAuth, Tines adds the authenticated user's email to the headers as email. You can reference it as:

  • <<headers.email>> in downstream actions

  • META.headers.email in tool formulas

For security, the Authorization header is not included in the captured headers when API key or OAuth authentication is used.

Other available headers

In addition to headers sent by the MCP client, Tines includes:

  • request_ip — the client's IP address

  • request-method — the HTTP method (typically POST)

  • content-type — the request content type

  • date — the date the request was received

To disable header capture entirely, turn off Include headers in the MCP server configuration. When disabled, neither <<headers.*>> nor META.headers.* will be available.

Other configuration options

The description of the MCP server action will be exposed directly to clients as instructions, in case you wish to share general context about the MCP server with the LLM using it.

Each tool in an MCP server can include optional annotations that describe its behavior to MCP clients. These hints help clients make decisions about how and when to invoke tools.

To configure hints, expand the Tool hints section below each tool's configuration.

MCP servers share many of the configuration options that webhooks offer. For example, you can set these like you would on a normal webhook:

  • Enable CORS

  • Match rules

  • Rate limiting

Was this helpful?
MCP server | Docs | Tines