MCP

Spantail speaks the Model Context Protocol (MCP), so AI clients can log and manage work entries, search, read agent activity, and create and read reports against your instance through their own tools. MCP is a client of the same REST API, so it respects the same permissions as your token.

The tool set is deliberately smaller than the CLI: operations with interpersonal side effects — sending reports, share links, comments, the inbox — stay human-initiated.

Two ways to connect

• Remote endpoint — your instance exposes <instance>/mcp over HTTP. Use this if your client supports remote MCP servers.
• Stdio server — run spantail mcp locally (from the CLI) for clients that only support stdio servers. It uses your saved CLI credentials.

Authenticate

MCP authenticates with a personal API token (from Settings → API tokens), passed as a Bearer token. The token acts as you, with your permissions.

Agent access tokens are not accepted here — they are ingest-only and can only send agent activity, not call MCP tools. See Capturing agent activity.

Set up with Claude Code

If you use the Spantail plugin for Claude Code, it bundles this MCP server — set the plugin’s apiToken and skip the manual setup below.

The stdio server registers in one line:

claude mcp add spantail -- spantail mcp

For a direct HTTP connection, point your client at <instance>/mcp with your token as a Bearer credential instead.

Available tools

Tool	What it does
list_workspaces	List your workspaces (call first to resolve ids).
list_projects	List the projects in a workspace.
log_work	Create a work entry.
log_work_batch	Create up to 100 work entries in one atomic request (all or none). Entries with an externalId upsert instead of duplicating.
list_entries	List work entries, with optional filters.
update_entry	Update one of your work entries.
delete_entry	Delete one of your work entries.
search	Search your work entries and reports by text.
list_report_templates	List the instance’s report templates.
list_reports	List your saved reports.
get_report	Fetch a report, including its rendered Markdown.
preview_report	Render a report from a template, scope, and period without saving it.
create_report	Create a report; adopts the template’s suggested name when none is given.
update_report	Re-render an existing report with changed fields (new version).
list_agents	List your AI agents in a workspace (to resolve agent ids).
get_agent_stats	Aggregated AI-agent activity for a date window (totals, by date, by agent).
list_agent_entries	List AI-agent session entries with duration, token usage, and context.

Stdio-only tools

The stdio server (spantail mcp) additionally registers tools that read the local filesystem — the remote /mcp endpoint runs on the server and never offers them:

Tool	What it does
import_work_entries	Bulk-import work entries from a local JSONL file (same format and semantics as spantail entries import).