MCP server - Chief Help

chief-mcp is a Model Context Protocol server for Chief. It lets any MCP client — Claude Code, Claude Desktop, Cursor, or Codex — manage chats, assets, labels, actions, live sessions, skills, and memories directly in your Chief project. Chief hosts the server at https://mcp.chief.bot/mcp. It uses Streamable HTTP, so compatible clients can connect without installing a binary or running a local process. The open-source server is a static Go binary built on the Go SDK and talks only to the Chief public REST API.

This is Chief as an MCP server. Chief can also act as an MCP client and call out to your own servers from inside a chat — that’s a separate feature, covered in MCP servers — connecting custom tools.

To get started with the hosted server you need three things: a Chief Personal Access Token, a project ID, and an MCP client — Claude Code, Claude Desktop, Cursor, Codex, or VS Code. See MCP clients for ready-to-paste hosted configurations.

A Claude Code session using the Chief MCP tools to list the files uploaded to a project — Claude Code calling Chief over MCP — one prompt, your real files.

Connect to the hosted server

Point any Streamable HTTP client at https://mcp.chief.bot/mcp. Authenticate each request with X-API-Key: <personal-access-token> and select a project with X-Project-Id: <project-id>. Clients limited to the Authorization header can send Authorization: Bearer <personal-access-token> instead.

claude mcp add chief --transport http https://mcp.chief.bot/mcp \
  --header "X-API-Key: <personal-access-token>" \
  --header "X-Project-Id: <project-id>"

The Projects tools need only the PAT. Most other tools are project-scoped and need the project header.

Optional self-hosted install

Homebrew is the recommended install on macOS:

brew install --cask Storytell-ai/tap/chief-mcp

go install github.com/Storytell-ai/chief-mcp@latest

go install requires a Go toolchain. Prebuilt binaries for each platform are on the releases page.

Credentials

A Chief Personal Access Token is required and sent as the API key. Most tools are project-scoped and also need a project id. Pass credentials as flags or read them from the environment:

Flag	Environment variable	Required
`--api-key`	`CHIEF_API_KEY`	yes
`--project`	`CHIEF_PROJECT_ID`	for project-scoped tools
`--base-url`	`CHIEF_BASE_URL`	no (defaults to `https://api.storytell.ai`)

Create a token in the Chief app under Settings → API tokens — see Introduction for tokens and project ids, or the help center’s API access & personal access tokens for the click-by-click version.

Security

Treat your Personal Access Token like a password. Pass it through CHIEF_API_KEY rather than committing it into a client config file.
A token only reaches the projects it is scoped to. Set CHIEF_PROJECT_ID (or the X-Project-Id header in HTTP mode) to bound the server to one project.
--insecure disables TLS verification and is for local development only.

Tools

The server exposes 44 tools across seven resources.

Resource	Tools
Chats	`create_chat`, `list_chats`, `get_chat`, `update_chat`, `delete_chat`, `send_message`, `list_messages`, `get_message`, `delete_message`
Assets	`upload_file`, `list_assets`, `get_asset`, `update_asset`, `delete_asset`
Labels	`create_label`, `list_labels`, `get_label`, `update_label`, `delete_label`, `attach_label`, `detach_label`
Actions	`create_action`, `list_actions`, `get_action`, `update_action`, `delete_action`, `enable_action`, `disable_action`
Live sessions	`list_sessions`, `get_session`, `update_session`, `delete_session`
Skills	`create_skill`, `list_skills`, `get_skill`, `update_skill`, `delete_skill`, `enable_skill`, `disable_skill`
Memories	`create_memory`, `list_memories`, `get_memory`, `update_memory`, `delete_memory`

What you can ask it

Once the server is connected you drive it in plain language — your agent picks the right tools and chains them. The tools above map to requests like:

“What did we decide about pricing in the last few chats?” — the agent calls list_chats and get_chat to read recent conversations, then answers from them.
“Upload every PDF in this folder and tag them contracts.” — upload_file per file, then create_label and attach_label.
“Summarize the most recent live session.” — list_sessions, then get_session.
“Create an action that emails me a summary of new assets every morning.” — create_action with a schedule.
“Remember that I always want answers in metric units.” — create_memory.

Because the agent decides which tools to call, the exact sequence varies from run to run — the same request can resolve through different tools and still be correct. Give it the goal (“find and summarize…”), not a tool name, and let it plan the calls. A server only sees the project it is scoped to, so to work against a different project, point it there with CHIEF_PROJECT_ID.

Transports

The vendor-hosted endpoint uses Streamable HTTP at https://mcp.chief.bot/mcp. If you choose to run the binary yourself, two transports are selected by subcommand:

stdio (default) — for a local agent that launches the binary as a subprocess.
http — for remote or web-based agents. Each request authenticates from its headers: the API key as a Bearer token in Authorization (or X-API-Key), and the project in X-Project-Id.

# Local agent (stdio).
chief-mcp stdio

# Remote agent (http) on :8080 at /mcp.
chief-mcp http --addr :8080 --path /mcp

Option	Applies to	Description
`--api-key`	stdio	Chief API key (env `CHIEF_API_KEY`)
`--project`	both	Default project id (env `CHIEF_PROJECT_ID`)
`--base-url`	both	API base URL (env `CHIEF_BASE_URL`)
`--insecure`	both	Skip TLS verification (local dev only)
`--debug`	both	Dump HTTP requests and responses
`--addr`	http	Address to listen on (default `:8080`)
`--path`	http	Path to mount the endpoint on (default `/mcp`)

In HTTP mode the server authenticates each request from its headers, so --api-key applies to stdio only. --project sets the default project for requests that omit X-Project-Id.

Configure a client

The fastest path is the hosted endpoint, which needs no local installation. See MCP clients for hosted Claude Code and Cursor setup. For an optional self-hosted stdio setup, the chief CLI writes a ready-to-paste config prefilled with the installed binary path and your credentials:

chief mcp config claude   # Claude Code / Claude Desktop
chief mcp config cursor   # Cursor
chief mcp config codex    # Codex

Only installed chief-mcp? Use the hand-written snippets on MCP clients instead — they need no extra tooling.

chief mcp config claude printing an MCP server JSON snippet — chief mcp config prints a ready-to-paste server snippet with your credentials filled in.

For hand-written config and the full per-client setup, see MCP clients.

Troubleshooting

Authentication failed — confirm CHIEF_API_KEY is set in the server’s environment (or sent as a header in HTTP mode) and that the token is valid. chief doctor checks credentials and connectivity.
A tool returns “not found” — confirm the id exists in the project the server is scoped to (CHIEF_PROJECT_ID). A wrong or missing project id is the usual cause.
The client doesn’t list the server or its tools — restart the client session. MCP servers are launched once and don’t hot-reload after a config change.
Inspect the traffic — add --debug to dump every HTTP request and response the server makes.

FAQ

Is there a hosted Chief MCP endpoint I can point my agent at?

Yes. Connect a Streamable HTTP client to https://mcp.chief.bot/mcp with your PAT and, for project-scoped tools, an X-Project-Id header.

Which MCP clients are supported?

Any MCP client. Claude Code, Claude Desktop, Cursor, Codex, and VS Code are the ones covered in these docs — see MCP clients for per-client config.

How many tools does the server expose?

44 tools across seven resources: chats, assets, labels, actions, live sessions, skills, and memories.

My client does not list the server or its tools. Why?

Restart the client session. MCP servers are launched once and do not hot-reload after a config change.

Do I need the chief CLI to use the MCP server?

No. The hosted server needs no CLI or local binary. Use the CLI only if you want it to generate configuration for an optional self-hosted stdio setup.

Can one server reach more than one project?

A server only sees the project it is scoped to. Point it at a different project with CHIEF_PROJECT_ID, or send X-Project-Id per request in HTTP mode.

​Connect to the hosted server

​Optional self-hosted install

​Credentials

​Security

​Tools

​What you can ask it

​Transports

​Configure a client

​Troubleshooting

​FAQ

Connect to the hosted server

Optional self-hosted install

Credentials

Security

Tools

What you can ask it

Transports

Configure a client

Troubleshooting

FAQ