Connect your agent

Your agent talks to Slicemap over MCP, by address. Nothing is installed on your machine: you give the agent the address and a personal key, and it can read and update your map.

Before you start

• You need an account on app.slicemap.dev. When you sign up, Slicemap creates a workspace for you, and you are its owner.
• Only owners and admins of a workspace can create keys.
• A key opens one workspace: the one on whose settings page you created it. An agent with that key sees only that workspace’s projects. For a project in another workspace, switch to that workspace and create a key there.

1. Create a key

1. In the sidebar, open Settings. The API Keys page opens.
2. Click Create key.
3. Give the key a name you will recognize later, for example “Claude Code”.
4. Under Access, choose Read & write. With Read only, the agent can look at the map but can’t take a story into work or tick a criterion.
5. Click Create key.

The key is shown once. Copy it before you close the dialog: Slicemap doesn’t show it again. If you lose it, create a new one.

2. Add Slicemap to your agent

The dialog with your new key already shows these setups with the key filled in. You can copy from there, or copy from here and replace <your-api-key> with your key.

Claude Code

Run this once in a terminal. Slicemap becomes available in every project on this machine.

claude mcp add --scope user --transport http slicemap https://app.slicemap.dev/api/mcp --header "Authorization: Bearer <your-api-key>"

Codex

Add this to ~/.codex/config.toml (on Windows %USERPROFILE%\.codex\config.toml). The Codex terminal, IDE extension and app share this file.

[mcp_servers.slicemap]
url = "https://app.slicemap.dev/api/mcp"
http_headers = { Authorization = "Bearer <your-api-key>" }

Cursor and others

Add this to the MCP settings of Cursor or any other agent that can connect to an MCP server by address.

{
  "mcpServers": {
    "slicemap": {
      "url": "https://app.slicemap.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Then restart the agent so it picks up the new server.

3. Check the connection

Ask your agent:

list my Slicemap projects

It calls slicemap_list_projects and answers with the projects of the key’s workspace. If you have no projects yet, the list is empty: create one in the app, or ask the agent to create it.

Next: Your first story with the agent.

If it doesn’t work

A problem with the key shows up as Slicemap not connecting at all: the server answers with HTTP 401 before any tool call, and the agent only reports that the server is not available. You see the text below in your client’s MCP log, or by calling the address with curl. A refusal on a single call comes back to the agent as text that ends with a code in parentheses. Here are the most common ones, word for word.

The key is missing. The agent’s config has no Authorization header. Check that the setup above was copied whole.

No access token. Send it as `Authorization: Bearer <token>`; issue one in Settings → API Keys.

The placeholder is still there, or the key was copied in part. Every key starts with sm_pat_.

This is not a Slicemap access token - they start with "sm_pat_".

The key was revoked, mistyped, or its owner left the workspace. Create a new key on the API Keys page.

This access token is not valid any more - it was revoked or never existed. Issue a new one in Settings → API Keys.

The key is read-only. The agent can read the map but not change it. A key’s access can’t be changed: create a new key with Read & write and replace the old one in the agent’s config.

"slicemap_estimate_story" needs the "write" right; this token carries [read]. Issue a token with it in Settings → API Keys. (insufficient_permissions)

The project is in another workspace. The refusal names the key’s workspace. If the project is in another workspace you belong to, it also names that workspace and the page where you can create the right key.

No project "my-app" in workspace "Personal". A token only sees the workspace whose Settings → API keys page issued it. "my-app" is in workspace "Studio" (/w/studio/settings/api-keys): issue a key on that page and use it instead of this one. (not_found)

Every other refusal, with what to do about it: Refusals.