MCP Integration

Connect AI coding assistants with one shared Basalt MCP URL.

Overview

What is MCP?

MCP (Model Context Protocol) is an open standard for connecting AI assistants to external data sources. Basalt exposes one shared remote MCP endpoint that AI tools — Codex, Claude Code, Cursor, VS Code, and others — can use to access your studio's live data directly.

Instead of manually copying project details into a chat, your AI assistant can query your projects, tasks, and notes on demand, and create or update records when you ask.

MCP URL

The Basalt MCP URL is https://basaltpms.com/api/mcp. It is the same for every studio and does not include company_id.

You can also open Settings → Integrations → MCP to copy the URL or a ready command/config for your client. Only users with the Admin or Owner role can authorize MCP access. When you connect an AI client for the first time, it opens a browser window for OAuth — sign in with your Basalt account, choose the studio, and approve the requested scopes.

Available Tools

Read Tools (mcp:read)

These tools are available with the mcp:read scope and provide read-only access to your studio data:

Tool	Description
`search`	Full-text search across projects, tasks, and notes
`fetch`	Retrieve any resource by URL
`list_projects`	List studio projects with optional filters
`get_project`	Get full details for a project
`list_todos`	List tasks with filters: status, priority, assignee
`get_todo`	Get full details for a task, including subtasks
`list_notes`	List studio notes
`get_note`	Get the content of a note

Write Tools (mcp:write)

These tools require the mcp:write scope and enforce the same role-based permissions as the Basalt UI. Delete operations are not exposed via MCP.

Tool	Description
`create_todo`	Create a task (manager+ role required)
`update_todo`	Update a task (manager+ or author/assignee)
`complete_todo`	Mark a task as completed
`create_project`	Create a project (manager+ role required)
`update_project`	Update project details (manager+ role required)
`create_note`	Create a note
`update_note`	Update a note (owner or shared-edit permission)

Client Setup

Fast Setup from Basalt

The shared endpoint is https://basaltpms.com/api/mcp. The easiest path is to copy a ready command or config from Settings → Integrations → MCP; Basalt shows ready options for Codex, Claude Code, Cursor, and VS Code.

After the client connects, OAuth opens in the browser and asks which Basalt account and studio should be bound to that client.

Codex

Add Basalt once from the terminal:

codex mcp add basalt --url 'https://basaltpms.com/api/mcp'

If your Codex client asks for login separately, run codex mcp login basalt. OAuth opens in the browser and asks you to choose the Basalt account and studio.

Claude Code

Add Basalt as a user-scoped MCP server so it is available across all your projects:

claude mcp add --transport http basalt --scope user 'https://basaltpms.com/api/mcp'

Then run /mcp inside Claude Code to complete OAuth authentication and choose the studio.

Claude Desktop & Claude.ai

Use the Connectors UI — not the config file — for remote MCP servers:

Open Customize → Connectors
Click Add custom connector
Paste the shared Basalt MCP URL
Click Connect and complete OAuth in the browser

For organization plans, a workspace admin may need to allow custom connectors first.

Cursor

Add Basalt to your global Cursor MCP config at ~/.cursor/mcp.json:

{"mcpServers":{"basalt":{"url":"https://basaltpms.com/api/mcp"}}}

Then run the following command to authenticate, or add the same URL via Cursor Settings → MCP:

cursor-agent mcp login basalt

Windsurf

Open Windsurf Settings → Cascade → MCP Servers → Add Server
Select Streamable HTTP
Paste the shared Basalt MCP URL
Complete OAuth in the browser

VS Code / GitHub Copilot

Open the Command Palette (Cmd/Ctrl+Shift+P)
Run MCP: Add Server
Choose Workspace or Global
Paste the shared Basalt MCP URL and complete OAuth

Cline & Gemini CLI

Cline

cline mcp add basalt 'https://basaltpms.com/api/mcp' --type http

Gemini CLI

gemini mcp add -s user -t http basalt 'https://basaltpms.com/api/mcp'

Both clients prompt for OAuth when they first connect to the server.

Scopes & Security

Permission Scopes

When authorizing, choose the scope that matches your needs:

mcp:read — read-only: list and search projects, tasks, and notes
mcp:write — additionally allows creating and updating records (subject to your role in the studio)

Scopes cannot be expanded silently — re-authorization is required to gain additional permissions. Refresh tokens always reuse the original scope.

Revoking Access

To stop local access, remove or disconnect the Basalt MCP server inside the AI client.

Basalt also invalidates MCP access when a user leaves the studio or loses the required Admin/Owner role. Server-side revocation invalidates access tokens, refresh tokens, and authorization codes for the affected client; subsequent tool calls return a 401 error.

Rate Limits & Current Limitations

Rate limits:

Any tool call: 120 per minute per client and IP
Write tool calls: 30 per minute per user and IP

Current limitations:

One selected studio per issued token
No portal or finance tools
Delete operations are not supported