MCP tools

Long Tail is an MCP server. Any MCP client (Claude Code, Claude Desktop, Cursor, a custom agent) connects to one endpoint and reads state, works queues, runs workflows and inspects execution through the same tools. This reference lists every built-in tool, its parameters and who may call it.

The endpoint

URL	POST https://<host>/mcp
Transport	Streamable HTTP, stateless: one request and one response per call
Auth	Authorization: Bearer <token>: an OAuth access token (people), a service-account key (machines), or a signed user token (JWT)
Methods	POST /mcp carries JSON-RPC (initialize, tools/list, tools/call). GET and DELETE answer 405

The host’s session cookie does not authenticate /mcp. A missing or invalid token answers 401; when the OAuth server is enabled, the 401 carries a WWW-Authenticate: Bearer resource_metadata="..." challenge so clients discover how to sign in.

Connect a client

With OAuth (people)

1. Add the server to Claude Code:

   claude mcp add --transport http long-tail https://lt.acme.dev/mcp

2. Run /mcp in Claude Code and pick Authenticate. The browser opens the consent page, which shows the app, the account and where it returns.

3. Choose what the client may do:

   Choice	The client may
   Allow read-only	Read what you can read, and run workflows marked read-safe
   Allow as me	Do anything you can do: claim, resolve, invoke and administer wherever your roles allow

Allow as me appears only when it grants more than read-only. Either way the client acts as you: every result is limited to your roles and every action is recorded as you.

Access tokens last 5 minutes. The client refreshes them with a refresh token that rotates on each use and lasts 30 days. Every request reads the grant, so a disconnected app, a revoked token or a deactivated account stops working on the next request. Disconnect a client under Connected apps in the user menu.

Enable the OAuth server with auth.oauthServer in start() or LT_OAUTH_ISSUER in the environment. Loopback redirects (Claude Code, Claude Desktop) are always allowed; an https redirect must appear in allowedRedirectUris. See OAuth delegation.

With a service-account key (machines)

Create a service account under Accounts → Service Accounts, assign its roles, then generate an API key with a scope. The raw key is shown once. The same is available as tools: create_bot_account, then create_bot_api_key.

.mcp.json

{
  "mcpServers": {
    "longtail-prod": {
      "type": "http",
      "url": "https://lt.acme.dev/mcp",
      "headers": { "Authorization": "Bearer ${LONGTAIL_PROD_KEY}" }
    }
  }
}

Reference the key as ${VAR} so the file holds no secret. Add one entry per environment (longtail-local, longtail-staging, longtail-prod); each keeps its tools under its own server name, so you pick one by naming the environment in the prompt.

Access and scopes

Two checks decide what a connected client can do. Both must pass.

Scope decides read or write. A key carries mcp:read (read-safe tools only) or mcp:read plus mcp:full (every tool). An OAuth grant of Allow read-only behaves like mcp:read.

Role decides which tools and which records. Each tool declares a gate, and a tool appears only to accounts that hold it:

Gate	Who holds it	Tools
caller	Any account	Escalations, tasks, workflow invocation, a run’s status and history, scan codes, docs, reads of users, roles and configuration, the account’s own OAuth connections
admin	Admin or superadmin	Workflow configuration, diagnostics, pruning, assigning and removing a user’s roles
builder	Superadmin, or the engineer role	Users, bot accounts, knowledge, YAML workflows, agents, topics, MCP server connections, control plane, workflow envelopes and state exports, terminating workflows, HTTP requests, file reads and writes, Claude Code tasks
roleManager	Admin, superadmin, or the engineer role	Roles, personas, scan rules, announcements
superadmin	Superadmin	The human-queue tools workflows use to create and resolve escalations

Within a tool, the account’s role decides whether the action is allowed on a given target. An account with mcp:full and only the reviewer role resolves reviewer escalations; it cannot route work to another role’s queue or manage users.

Caution

builder includes registering an MCP server with the stdio transport, which runs a command on the Long Tail host. Grant the engineer role with the same care as host access.

Exposure control

Deployment-wide settings in start({ mcp: { exposure } }) filter the surface before scopes apply:

Option	Type	Default	Effect
readOnly	boolean	false	Expose only read-safe tools to every key and grant
hideAiWhenUnavailable	boolean	true	Hide AI-required servers when no ANTHROPIC_API_KEY or OPENAI_API_KEY is set
allowServers	string[]	all shipped	Server allowlist
denyServers	string[]	none	Server denylist

Read-safe tools

Every tool is read-safe (reports state, changes nothing) or a write. Each tool page shows Read-safe: Yes or No next to its gate. A read-scoped key, a read-only OAuth grant, or exposure.readOnly exposes the read-safe set only. A tool missing from its server’s manifest counts as a write.

Workflows join the read-safe set one at a time. A workflow whose config carries read_safe: true (a side-effect-free lookup) is invocable by read-scoped callers through invoke_workflow_read_safe. One without the flag fails with a clear error.

Compile hints

A server may carry compile hints: short notes on how its tools wire together (argument names, output fields, which step follows which). Long Tail’s LLM-driven workflows read them alongside the server’s tool list when they plan tool calls, and the YAML compiler reads them when it turns an execution into a deterministic workflow. Each server page prints its hints.

Tool names at /mcp

/mcp merges every server into one tool list. When two servers register the same name, the later server’s tool gets its short server name as a prefix. Four tools carry a prefix: admin_resolve_escalation, admin_accumulate_item, admin_remove_item and events_list_topics.

Built-in servers

Server	ID	Purpose	AI required	Tools	Read-safe
Admin	long-tail-admin	Tasks, escalations, workflows, diagnostics, agents, accounts, control plane, roles, personas, scan codes, settings	No	119	52
Human queue	long-tail-human-queue	Escalation primitives workflows use: create, wait, claim, resolve, fill batches and accumulators	No	10	3
Knowledge	long-tail-knowledge	Versioned JSONB knowledge store in isolated domains	No	10	5
Events	long-tail-events	Publish events and browse the topic catalog	No	4	2
File storage	long-tail-file-storage	Read, write, list and delete files in managed storage	No	4	2
HTTP fetch	long-tail-http-fetch	HTTP requests to external URLs	No	3	0
Schema exchange	long-tail-schema-exchange	Schema-validated requests to external endpoints with credential resolution	No	2	1
OAuth	long-tail-oauth	Fresh access tokens for connected external services	No	3	1
Docs	long-tail-docs	List, search and read the product documentation	No	3	3
Vision	long-tail-vision	Image analysis and description with an LLM	Yes	2	2
Translation	long-tail-translation	Text translation with source language detection	Yes	1	1
Claude Code	long-tail-claude-code	Agentic development tasks through the Claude Code CLI	Yes	2	1

That is 163 tools, 73 of them read-safe. get_escalation_lookups on the human-queue server is registered for in-process workflow use, so /mcp lists 162.

Related

MCPAgents work the same queues as people.

IdentityRoles, scopes and service accounts.

OAuth delegationLet a client act as a signed-in person.

HTTP referenceThe REST routes behind each tool.