Claude Code MCP server setup for a project backlog

Add the Autoplans MCP server to Claude Code so the agent reads its tasks, checks dependencies and updates status from the terminal.

The configuration

File: .mcp.json in the project root, or ~/.claude.json for every project · Transport: Streamable HTTP

{
  "mcpServers": {
    "autoplans": {
      "type": "http",
      "url": "https://autoplans.dev/api/v1/mcp",
      "headers": { "Authorization": "Bearer apk_live_..." }
    }
  }
}

The endpoint is https://autoplans.dev/api/v1/mcp. Create the key in the dashboard under Settings → API keys; see Accounts and API keys.

Step by step

1
Create an API key in the dashboard under Settings → API keys.
2
Save the block above as .mcp.json in the repository root, or put the same server entry in ~/.claude.json to have it in every project.
3
Replace apk_live_... with the key, or with ${AUTOPLANS_API_KEY} and export that variable in the shell you start Claude Code from — the file is expanded when it is read.
4
Skip the file altogether if you prefer, and run claude mcp add --transport http autoplans https://autoplans.dev/api/v1/mcp --header "Authorization: Bearer apk_live_..." to have the entry written for you.
5
Restart Claude Code and approve the project-scoped server the first time it is offered.
6
Run /mcp and check that autoplans reports Connected; claude mcp list says the same from the shell.

Specific to Claude Code

•.mcp.json is project scope: it is meant to be committed, and each teammate is asked to approve the server the first time it is used. claude mcp reset-project-choices clears those answers. ~/.claude.json is the private file — a top-level entry there applies to every project, a project entry only to that folder.
•Claude Code expands ${VAR} and ${VAR:-default} inside url, headers, command, args and env, so "Authorization": "Bearer ${AUTOPLANS_API_KEY}" keeps the key out of a file you commit. An unset variable with no default is left unexpanded and warned about.
•Keep the "type": "http" line. Claude Code documents an entry that has url but no type as a configuration error, and reads it as a stdio server, so dropping the field turns a working endpoint into a command that does not exist.
•What this buys is Claude Code project context that outlives the session. The tasks live in your Autoplans account rather than in the context window, so the next session — or a session in another client — opens on the same plan.
•The Autoplans plugin is the other route: /plugin marketplace add mohamedgb00714/autoplans-plugins then /plugin install autoplans. It adds this same MCP server plus the /plan, /start, /tasks and /finish skills and the autoplans-planner agent. See /docs/claude-code.

What the agent can do once connected

Around forty tools: list and create projects, read the whole task graph in one list_tasks call, ask code_agent_get_task_with_dependencies whether a task is blocked, move it to in progress, comment on it, and mark it done. Every tool and its arguments is in the MCP tools reference; the server itself is described on the MCP server page.

curl -s https://autoplans.dev/api/v1/mcp \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $AUTOPLANS_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Questions

How do I add an MCP server to Claude Code?

Put the block above in .mcp.json at the root of the repository, or run claude mcp add --transport http autoplans https://autoplans.dev/api/v1/mcp --header "Authorization: Bearer apk_live_...". Restart the session and run /mcp; autoplans should be listed as connected. One file holds any number of servers, so this sits alongside the ones you already have.

Should .mcp.json go in the repository or in my home directory?

Both work and they mean different things. .mcp.json in the repository root is shared through version control, so everyone who clones the project gets the same backlog once they approve the server. ~/.claude.json is yours alone: a top-level entry there applies to every project, and a project-keyed entry applies only to that folder. Keys are personal, so most teams commit the entry with ${AUTOPLANS_API_KEY} in the header and let each developer export their own.

Does this give Claude Code project context that survives a restart?

Yes, because the plan is not held in the conversation. Tasks, dependencies, comments and status live in your Autoplans account, and every session reads them through the same tools. Closing the terminal loses the conversation, not the project state. If the repository also contains .autoplans/project.json, the agent can go straight to the right project instead of listing them all.

Why does /mcp show autoplans as failed?

Three usual causes. The key is missing or wrong, and the endpoint answers 401. The account is on the free plan, and the endpoint answers 403 with an upgrade message, because the hosted MCP server is a paid capability. Or ${AUTOPLANS_API_KEY} was never exported in the shell Claude Code was started from, in which case Claude Code warns and sends the literal ${AUTOPLANS_API_KEY} text as the token. Curl the endpoint with a tools/list request to tell them apart; a working key returns a result with a tools array.

Checked against the Claude Code documentation on 2026-08-28.