MCP servers for an integrated account

Create an MCP server for one connected account and hand its URL to an AI agent. The agent sees that account's Proxy APIs as tools, and nothing else: no other accounts, no other tenants.

This page covers the per-integrated-account MCP server. For the workspace-wide server that calls the Truto platform API, see Platform MCP server.

truto mcp-tokens create <integrated_account_id> --name support-agent

Before you start

• Plan. MCP servers are a plan feature. On a plan without them, creating one fails with MCP server creation is not available on your current plan. Contact support@truto.one to change your plan.
• Described tools. The server exposes the account's tools: Proxy API methods that have a description. If the account has none, creating a server fails with This integration is not yet AI-ready. Add descriptions to the integration's methods (see Adding tools to an integration) or contact support.
• Limit. Each integrated account can have up to 10 MCP servers. Delete one you no longer use to make room.

1. Create the server

From the console

1. Open the account at Integrated Accounts → your account → MCP Servers (app.truto.one/integrated-accounts/<id>/mcp-servers).
2. Click Create MCP Server.
3. Fill in the modal:
   • Name of the MCP Server (required) — a label to identify it.
   • Method — leave empty for all methods, or pick read, write, or individual method names such as list or search.
   • Tags — leave empty for all tools, or pick resource tags to narrow the tool set.
   • Tool exposure — All tools or Discovery (3 meta-tools). See Tool exposure.
   • Expires At — optional date and time after which the server stops working.
   • Require Auth — when on, every request must also carry a Truto API token. See Requiring an API token.
4. Click Create MCP Server, copy the URL, tick I have copied my MCP Server URL shown above, and click Done.

From the API

POST /integrated-account/:id/mcp creates a server. Only name is required.

Every method you list must match at least one tool on the account, and the combination of methods and tags must match at least one tool; otherwise the request returns 400 and names the methods and tags that are available.

truto mcp-tokens create <integrated_account_id> \
  --body '{"name":"Support agent (read-only)","config":{"methods":["read"],"tags":["support"]},"expires_at":"2026-12-31T23:59:59.000Z"}'

curl -X POST https://api.truto.one/integrated-account/<integrated_account_id>/mcp \
  -H "Authorization: Bearer <API token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support agent (read-only)",
    "config": {
      "methods": ["read"],
      "tags": ["support"],
      "tool_exposure": "all",
      "require_api_token_auth": false
    },
    "expires_at": "2026-12-31T23:59:59.000Z"
  }'

server = await truto_api.integrated_accounts.create_mcp_server(
    "<integrated_account_id>",
    {
        "name": "Support agent (read-only)",
        "config": {"methods": ["read"], "tags": ["support"]},
        "expires_at": "2026-12-31T23:59:59.000Z",
    },
)
print(server["url"])

The response is the server record plus two fields that are only returned here:

{
  "id": "2ba1f401-7183-47c5-9e39-e8e257e3c796",
  "name": "Support agent (read-only)",
  "integrated_account_id": "1ba1f401-7183-47c5-9e39-e8e257e3c795",
  "config": { "methods": ["read"], "tags": ["support"] },
  "expires_at": "2026-12-31T23:59:59.000Z",
  "created_by": "0c1a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8",
  "created_at": "2026-11-02T10:00:00.000Z",
  "updated_at": "2026-11-02T10:00:00.000Z",
  "token": "4f1c5e0b6c2d4f8a9b3c5d7e9f0a1b2c",
  "url": "https://api.truto.one/mcp/4f1c5e0b6c2d4f8a9b3c5d7e9f0a1b2c"
}

Store url (or token) as a secret. Anyone holding it can call the account's tools, unless the server requires an API token.

2. Connect an MCP client

The server speaks JSON-RPC over HTTP POST to https://api.truto.one/mcp/<token> (the Streamable HTTP transport). Paste the URL into any client that supports remote HTTP MCP servers.

claude mcp add --transport http hubspot-support https://api.truto.one/mcp/<token>

{
  "mcpServers": {
    "hubspot-support": {
      "url": "https://api.truto.one/mcp/<token>"
    }
  }
}

{
  "mcpServers": {
    "hubspot-support": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.truto.one/mcp/<token>"]
    }
  }
}

For Cursor, put the config in .cursor/mcp.json or ~/.cursor/mcp.json. For Claude Desktop, put it in claude_desktop_config.json and restart the app.

To check the server from code before handing it to an agent, send tools/list yourself:

curl -X POST https://api.truto.one/mcp/<token> \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

import TrutoApi from '@truto/truto-ts-sdk'
 
const trutoApi = new TrutoApi({ token: process.env.TRUTO_API_TOKEN })
 
const tools = await trutoApi.mcp.listTools('<token>')
const result = await trutoApi.mcp.callTool('<token>', '<tool_name>', {})

tools = await truto_api.mcp.list_tools("<token>")
result = await truto_api.mcp.call_tool("<token>", "<tool_name>", {})

Take tool names and their input schemas from tools/list. A tool call returns a text block holding JSON with result, next_cursor, prev_cursor, and request_id.

Tool exposure

• all — tools/list returns every tool that matches the server's methods and tags, each with its input schema. Simple, but a large integration can fill the agent's context with schemas.
• discovery — tools/list returns three tools, and the agent finds the rest on demand:
  • search_tools — takes a query (for example "list contacts") and an optional limit (default 5, max 20). An empty query browses every tool grouped by resource. Returns names, descriptions, and tags.
  • get_tool_schema — takes tool_names, up to 5 names from search_tools, and returns their input schemas.
  • call_tool — takes tool_name and arguments and runs the tool.

Discovery still respects config.methods and config.tags: the agent can only find and call tools the server allows.

Requiring an API token

With config.require_api_token_auth set to true (Require Auth in the console), every request to the server URL must also send a Truto API token:

curl -X POST https://api.truto.one/mcp/<token> \
  -H "Authorization: Bearer <API token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Integrated account tokens are rejected; use an API token. Clients that can't send headers (Cursor's url config, for example) need a bridge such as mcp-remote with --header, as shown in Platform MCP server → Cursor.

Manage servers

List and get never return the token or URL. PATCH accepts name, config, and expires_at, and changes apply to the existing URL; the token stays the same. config is merged key by key, so {"config": {"tool_exposure": "discovery"}} keeps the server's methods and tags. Send "expires_at": null to remove an expiry.

truto mcp-tokens update <integrated_account_id> <mcp_server_id> --tool-exposure discovery

curl -X PATCH https://api.truto.one/integrated-account/<integrated_account_id>/mcp/<mcp_server_id> \
  -H "Authorization: Bearer <API token>" \
  -H "Content-Type: application/json" \
  -d '{"config": {"tool_exposure": "discovery"}}'

await truto_api.integrated_accounts.update_mcp_server(
    "<integrated_account_id>",
    "<mcp_server_id>",
    {"config": {"tool_exposure": "discovery"}},
)

In the console, click a server's name to open Edit MCP Server, or the trash icon to delete it. Deleting is permanent and the URL stops working. truto mcp-tokens delete asks for confirmation unless you pass --force.

When expires_at passes, Truto removes the server and its URL returns 404 with MCP Token not found or expired. Create a new server to restore access.

Debug with logs

Every request to a per-integrated-account MCP server is logged. Open Logs → MCP (app.truto.one/logs/mcp) and filter by integrated account, MCP server, and date range to see each MCP method, the tool called, the client name, and timings. See Viewing logs.

Next

Narrow what the agent can do by giving each use case its own server: a read-only server for a support assistant, a write server with a short expires_at for a one-off migration. To shape the tools themselves, edit method descriptions and schemas in the integration; see Tools overview. Full request and response schemas are in the MCP API reference.