Learn how to turn on Baton’s MCP server, connect an AI assistant to your workspace, create and revoke credentials, and control whether an assistant can read only or also write.
MCP Integration Overview
MCP (Model Context Protocol) lets AI assistants securely query data from your Baton workspace. Instead of copying project data into a chat window, you point the assistant at your workspace and it reads live data on demand — project health, task status, due dates, time entries, comments and more.
Access is always scoped to a single workspace, and it is read-only unless write access is granted. Writing means creating and updating tasks, posting comments, logging time, setting project health, and attaching files and links to projects and tasks.
There are two ways in:
Connected assistants — an assistant you sign into through a browser, such as Claude.ai. It asks for your approval on a consent screen, and appears under
Connected assistants.MCP keys — for tools that can’t sign in through a browser, such as MCP Inspector, Cursor, custom scripts and agents. These authenticate with a long-lived key.
Either can be revoked at any time, and neither ever reaches outside the workspace it was created in.
Enabling MCP for Your Workspace
MCP is enabled per workspace by Baton. There are two separate switches:
MCP Integration turns the feature on and makes the settings page visible.
MCP Write allows write access to be granted. Without it, every credential is read-only no matter how it was created.
They’re deliberately separate, so you can let assistants read your workspace without ever letting them change anything. Contact your Baton representative to have either enabled.
Once MCP Integration is on, head over to your workspace settings and you’ll find MCP Integration in the left-hand menu.
Who Can Use MCP
MCP is restricted to workspace managers — users with the Workspace Admin or Internal account type. Everyone else is refused, including read-only vendors, limited vendors, client users and third parties.
This is because MCP queries are scoped to the whole workspace rather than to the projects an individual belongs to. A limited user who could reach MCP would see far more than they can see in the app, so the door is closed rather than narrowed.
If you can’t see MCP Integration in your workspace settings, either the feature isn’t enabled for your workspace or your account isn’t a workspace manager.
Connecting an AI Assistant
Use this route for Claude.ai and any other assistant that signs in through a browser.
Go to your workspace settings and select
MCP Integration.Copy the
Remote MCP Server URLat the top of the page. It looks likehttps://your-workspace.hellobaton.com/mcp.In your assistant, add a new custom connector and paste that URL.
The assistant sends you to Baton to approve the connection. Review what it’s asking for — the consent screen tells you whether it wants read access or read and write — then approve it.
The assistant now appears under
Connected assistants, showing who connected it and whether it hasRead onlyorRead & writeaccess.
You’re granting access as yourself, so anything the assistant does is recorded under your name.
Creating an MCP Key
Use this route for tools that can’t open a browser.
Go to your workspace settings and select
MCP Integration.In the
MCP keysection, select Create MCP Key.Give the key a name that describes what it’s for — it’s only for your own reference.
Decide whether to turn on Allow write access. It’s off by default.
Select Create, then copy the key from the
MCP Key Credentialsdialog.Pass it to your tool as an
Authorization: Bearer <key>header.
Copy the key before you close the dialog. Baton won’t show it again, and there’s no way to tell a read key from a write key after the fact other than the label on the list.
Choosing Read or Read & Write
Read or read & write is chosen per key when you create it, and can’t be changed afterwards. To change it, create a new key and delete the old one.
TLDR:
Read only (the default)
The assistant can query every collection your workspace exposes, run summaries, and read comments and attachments.
It can’t create, change or delete anything.
Nothing it does sends email.
Read & write
Everything above, plus creating and updating tasks, posting comments (including internal comments), logging time, setting project health, and attaching files and links.
Removing an attachment is the only delete available, and it’s permanent.
Some writes send real email to real people. See Important Notes below.
Write access needs both switches: the workspace must have MCP Write enabled and the credential must carry write access. A key marked Read & write in a workspace without MCP Write still can’t write.
What an Assistant Can Do
Reading
Assistants query your workspace through a single flexible query tool covering projects, tasks, milestones, companies, users, custom fields, time entries, comments, attachments, forms and activity history. There are also purpose-built summary tools that answer common questions without pulling thousands of rows:
workspace_info— what workspace this is, the current server time, and whether writes are on.portfolio_summary— a workspace-wide rollup: projects by status and health, task counts, and how many tasks are overdue.project_summary— the same idea for a single project.
Results are capped at 500 rows per query. When a result is cut short the assistant is told so explicitly, so it can narrow the query or page through rather than quietly reporting a partial answer as a complete one.
Writing
When write access is granted, an assistant can also create and update tasks, post comments, log time entries, set project health, attach files and links, and remove attachments.
Important Notes:
Some writes send email to your customers. Assigning a task emails the new assignee. Completing a task that requires sign-off emails the client champion. A status change emails that task’s watchers, and can auto-start dependent tasks, which emails their assignees. Treat a request like “close out these stale tasks” as a request to send that many emails.
Assigning a task changes project membership. Handing a task to someone who isn’t on the project adds them to it.
Everything is recorded under a person’s name. For a connected assistant that’s whoever approved it; for a key it’s whoever created it. The activity feed shows that person’s name with a marker noting it came through MCP.
Writes aren’t reversible from the assistant. A task, comment, time entry or health record created by mistake has to be removed by a person in Baton. Removing an attachment is permanent and can’t be undone anywhere.
A key belongs to the person who created it. It stops working if that account is deactivated or loses workspace-manager access. If someone leaves, their keys stop working — create a replacement rather than trying to transfer one.
Requests are rate limited to 60 per minute per credential, so a runaway agent can’t overwhelm your workspace.
Revoking Access
Both credential types are revoked from the same page, and both take effect on the assistant’s next request.
For a browser-connected assistant, find it under
Connected assistantsand select Revoke Connection.For a key, find it in the
MCP keylist and select Delete MCP Key.
Deleting a key can’t be undone. Any tool still using it will start receiving authentication errors immediately.