# 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](https://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 once in a terminal:

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

Codex—add to ~/.codex/config.toml:

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

Cursor and other MCP clients—add to the MCP settings:

```json
{
  "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:

```text
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](/docs/first-story/).

## 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.

```text
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_`.

```text
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.

```text
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.

```text
"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.

```text
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](/docs/reference/refusals/).