Documentation → How-to guides

Connect Claude to mapbench

Give Claude access to one of your mapbench projects, so it can add datasets, write SQL models, build maps and publish a link — working against your real data rather than something you pasted into a chat.

Before you start

A mapbench account. Accounts are created by invitation — request access if you do not have one.
The project you want Claude to work in, and permission to write to it. A connection can only ever reach projects you could reach yourself.
The mapbench server address: https://mapbench.app/mcp

Which route to take

You use	Route	How you sign in
Claude on the web, desktop and mobile.	Custom connector	You are sent to mapbench, log in, and approve an access screen
Claude Code, in a terminal	API key	You paste a key you minted yourself

The two are independent. Connecting one does not connect the other, and you can run both at once.

Route 1 — Claude on the web, desktop and mobile

Step 1. Create the connector in mapbench

Sign in to mapbench and open Account.
Go to the AI agent connectors tab.
Give the connector a name you will recognise later — e.g. Claude on the web — and choose Create connector.

mapbench then shows you three values: the server URL, a client ID and a client secret.

Copy the client secret now. It is shown once and never again. If you lose it, disconnect the connector and create another — there is no way to reveal it later.

Step 2. Add it in Claude

In Claude, open Settings → Connectors → Add custom connector.
Paste the server URL below into “Remote MCP server URL”.
Open Advanced settings and paste the client ID and secret.
Save, then choose Connect and approve the access screen.

The server URL is https://mapbench.app/mcp. The client ID and secret go under Advanced settings, not in the main form — a connector added without them will fail to connect.

Step 3. Approve the access screen

Choosing Connect sends you to mapbench's own login page. Sign in there, and you will be shown exactly what Claude is asking for:

See your datasets, models and maps, and run read-only SQL over them
Add and change datasets, their styling and folders
Create and change SQL models
Create and change maps and their layers
Cancel queued processing jobs
Create and revoke public share links to maps and datasets
Create and rename projects, and move this connection between the projects you can write

Approving completes the connection. Nothing is granted that is not on that list — in particular, Claude cannot delete anything. It can archive a dataset or a map, which you can undo.

Step 4. Check that it worked

Ask Claude something that only mapbench can answer, such as “which mapbench organisation and project am I connected to?” or “list my mapbench datasets”. A correct answer names your organisation and the project the connection is standing in.

Route 2 — Claude Code

Claude Code authenticates with an API key rather than a connector, so there is no approval screen and no browser round-trip.

Step 1. Mint a key

Sign in to mapbench and open Account → API keys.
Name the key, choose the project it will act in, and choose how much it may do:
- Read only — read your data and run read-only SQL over it.
- Full agent — the above, plus creating datasets, models and maps.
- Full agent + delete — the above, plus permanent deletion.
Copy the key. Like the client secret, it is shown once.

Step 2. Register the server

claude mcp add --transport http mapbench https://mapbench.app/mcp \
  --header "Authorization: Bearer tp_…"

Replace tp_… with the key you just copied. Run /mcp inside Claude Code to confirm the server is listed and connected.

Keys cannot publish share links. No key preset grants that, on purpose: turning revocable in-org access into a public URL stays a deliberate decision. If you need Claude Code to hand you a viewable link, ask your operator to mint a key with that permission explicitly, or use the connector route, whose grant includes it.

Which project the connection acts in

A connection acts in exactly one project at a time, with your permissions inside it. A connector starts in your default project; an API key starts in whichever project you picked when you minted it.

To move a connection, use the project selector next to it on Account. You do not have to disconnect and start again.
Claude can also move itself between projects you can write, if you approved that on the access screen. It cannot move data across a project boundary — that stays a manual, audited action.
If you lose access to the project a connection is pinned to, that connection stops working immediately rather than quietly falling back to another project.

Everything Claude does is attributed

Work done through a connection is recorded as the agent's, not yours: the activity history for a dataset or a map shows which connection made each change and when. That is the point of connecting an agent rather than sharing a login.

Disconnecting

Open Account, find the connector or key, and choose Disconnect or Revoke. Access ends immediately. The record of what that connection already did is kept, so past history stays attributable.

Troubleshooting

Claude refuses to add the connector, with no useful error: Almost always the server URL. It must be exactly https://mapbench.app/mcp — no trailing slash, and the /mcp on the end. Check too that the client ID and secret went into Advanced settings rather than being left blank.
The access screen says the connector belongs to someone else: Each connector is bound to the account that created it, and mapbench refuses to authorize one for anybody else. If you were sent an authorization link by another person, do not approve it — create your own connector instead.
Claude worked yesterday and now gets “no project access”: The connection is pinned to a project you are no longer a member of. Re-point it on Account, or ask a manager to restore your access to that project.
Claude says it cannot delete a dataset or map: Correct — deletion is not part of any connector grant, and mapbench offers an agent no delete tool at all. Ask it to archive the item instead, which is reversible, or delete it yourself in the app.
Claude says it cannot switch projects: That permission is named on the access screen and is not granted to API keys by any preset. Move the connection yourself on Account.
There is no “AI agent connectors” tab on my Account page: Connectors are switched off on this deployment. The Claude Code route above still works; ask your operator about enabling connectors.