MCP servers

These endpoints manage MCP server registrations, connections and tool invocations. See MCP for how registered servers feed tool discovery.

All endpoints require authentication. Registering, testing, updating, deleting, connecting and disconnecting servers requires builder access (superadmin or the engineer role).

A stdio server is a command Long Tail starts on its own host, with that host’s environment and network. Builder access therefore includes running commands on the host: grant the engineer role with the same care as host access.

List servers

GET /api/mcp/servers

Lists registered servers. transport_config is included only for builders.

Query parameters

Parameter	Type	Description
`status`	`string`	Filter by status: `registered`, `connected`, `error`, `disconnected`
`search`	`string`	Search server name, description or tool names (case-insensitive)
`auto_connect`	`boolean`	Filter by auto-connect flag
`tags`	`string`	Comma-separated tags for tag-based filtering
`limit`	`integer`	Max results (default: 50)
`offset`	`integer`	Pagination offset (default: 0)

Example request

curl "https://lt.acme.dev/api/mcp/servers?status=connected&tags=vision" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "servers": [
    {
      "id": "a1b2c3d4-...",
      "name": "mcp-vision-longtail",
      "description": "Vision analysis tools",
      "transport_type": "stdio",
      "transport_config": { "command": "node", "args": ["server.js"] },
      "auto_connect": true,
      "status": "connected",
      "tool_manifest": [
        { "name": "analyze_image", "description": "Analyze an image", "inputSchema": {} }
      ],
      "tags": ["vision", "image-analysis"],
      "compile_hints": "Use for image processing tasks",
      "credential_providers": ["openai"],
      "metadata": { "builtin": true },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

Register a server

POST /api/mcp/servers

Registers an MCP server.

Auth: Requires builder access (superadmin or the engineer role).

Request body

Field	Type	Required	Description
`name`	`string`	Yes	Unique server name
`description`	`string`	No	Human-readable description
`transport_type`	`string`	Yes	`stdio`, `sse`, or `streamable-http`
`transport_config`	`object`	Yes	Transport-specific config (see below)
`auto_connect`	`boolean`	No	Connect on startup (default: false)
`metadata`	`object`	No	Arbitrary metadata
`tags`	`string[]`	No	Tags for tool discovery (e.g. `["database", "analytics"]`)
`compile_hints`	`string`	No	Guidance for the workflow compiler when using this server’s tools
`credential_providers`	`string[]`	No	IAM providers required by tools (e.g. `["github", "slack"]`)

Transport config for stdio:

{ "command": "node", "args": ["server.js"], "env": {} }

Transport config for sse:

{ "url": "https://mcp.acme.dev/sse", "headers": { "Authorization": "Bearer <token>" } }

Transport config for streamable-http:

{ "url": "https://mcp.acme.dev/mcp", "headers": { "Authorization": "Bearer <token>" } }

headers is optional and is sent with every request to the server, the SSE stream included. Like the rest of transport_config, it is returned only to builders.

Example request

curl -X POST https://lt.acme.dev/api/mcp/servers \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-inventory",
    "description": "Inventory lookup tools",
    "transport_type": "streamable-http",
    "transport_config": { "url": "https://mcp.acme.dev/mcp" },
    "auto_connect": true,
    "tags": ["inventory"]
  }'

Response 201: Created server record.

Response 409: Server name already exists.

Get a server

GET /api/mcp/servers/:id

Returns one server record. transport_config is included only for builders.

Path parameters

Parameter	Type	Description
`id`	`string`	Server id

Example request

curl https://lt.acme.dev/api/mcp/servers/$SERVER_ID \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200: Server record.

Response 404: Server not found.

Update a server

PUT /api/mcp/servers/:id

Partial update of a server registration.

Auth: Requires builder access (superadmin or the engineer role).

Path parameters

Parameter	Type	Description
`id`	`string`	Server id

Request body: Any fields from the registration, including tags, compile_hints and credential_providers.

Example request

curl -X PUT https://lt.acme.dev/api/mcp/servers/$SERVER_ID \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["inventory", "orders"] }'

Response 200: Updated server record.

Response 404: Server not found.

Delete a server

DELETE /api/mcp/servers/:id

Removes a server registration.

Auth: Requires builder access (superadmin or the engineer role).

Path parameters

Parameter	Type	Description
`id`	`string`	Server id

Example request

curl -X DELETE https://lt.acme.dev/api/mcp/servers/$SERVER_ID \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{ "deleted": true }

Response 404: Server not found.

Test connection

POST /api/mcp/servers/test-connection

Tests connectivity to an MCP server without saving a registration. Long Tail creates a temporary client, connects, lists tools, then disconnects.

Auth: Requires builder access (superadmin or the engineer role).

Request body

Field	Type	Required	Description
`transport_type`	`string`	Yes	`stdio`, `sse`, or `streamable-http`
`transport_config`	`object`	Yes	Transport-specific config

Example request

curl -X POST https://lt.acme.dev/api/mcp/servers/test-connection \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "transport_type": "streamable-http", "transport_config": { "url": "https://mcp.acme.dev/mcp" } }'

Response 200

{
  "success": true,
  "tools": [
    { "name": "analyze_image", "description": "Analyze an image", "inputSchema": {} }
  ]
}

On failure:

{
  "success": false,
  "tools": [],
  "error": "Connection refused"
}

Connect to a server

POST /api/mcp/servers/:id/connect

Connects to the registered MCP server and caches its tool manifest.

Auth: Requires builder access (superadmin or the engineer role).

Path parameters

Parameter	Type	Description
`id`	`string`	Server id

Example request

curl -X POST https://lt.acme.dev/api/mcp/servers/$SERVER_ID/connect \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{ "connected": true, "serverId": "a1b2c3d4-..." }

Disconnect from a server

POST /api/mcp/servers/:id/disconnect

Disconnects from the server.

Auth: Requires builder access (superadmin or the engineer role).

Path parameters

Parameter	Type	Description
`id`	`string`	Server id

Example request

curl -X POST https://lt.acme.dev/api/mcp/servers/$SERVER_ID/disconnect \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{ "disconnected": true, "serverId": "a1b2c3d4-..." }

List tools

GET /api/mcp/servers/:id/tools

Returns the tools available on a connected MCP server.

Path parameters

Parameter	Type	Description
`id`	`string`	Server id

Example request

curl https://lt.acme.dev/api/mcp/servers/$SERVER_ID/tools \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "tools": [
    {
      "name": "analyze_image",
      "description": "Analyze an image using vision models",
      "inputSchema": {
        "type": "object",
        "properties": {
          "image_url": { "type": "string" }
        }
      }
    }
  ]
}

Call a tool

POST /api/mcp/servers/:id/tools/:toolName/call

Invokes a tool on a connected MCP server.

Auth: The tool runs as the caller, or as the execute_as account when given. A built-in tool requires the capability its manifest gate declares, checked for the acting account; a built-in tool with no gate requires builder access. A tool on an external server (any registered network or local-process server) requires builder access, since it runs on the credential stored with that server. execute_as follows the act-as rule: a superadmin may act as anyone, and a caller holding an admin-type grant may act as an account that holds no superadmin grant and whose every role the caller holds at the same or higher type.

Path parameters

Parameter	Type	Description
`id`	`string`	Server id
`toolName`	`string`	Tool name

Request body

Field	Type	Required	Description
`arguments`	`object`	No	Tool arguments
`execute_as`	`string`	No	Account id or `external_id` to run the tool as

Example request

curl -X POST https://lt.acme.dev/api/mcp/servers/$SERVER_ID/tools/analyze_image/call \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": { "image_url": "https://example.com/image.png" },
    "execute_as": "optional-account-id"
  }'

Response 200

{
  "result": {
    "content": [{ "type": "text", "text": "Analysis result..." }]
  }
}

Response 403: The caller may not act as execute_as, or the acting account lacks the tool’s capability.

Response 422 (missing credential):

{
  "error": "missing_credential",
  "provider": "openai",
  "message": "Credential required for provider: openai"
}