Skip to main content

Installation

This page covers the local install: running the Bolti MCP (Model Context Protocol) server on your machine with a Personal Access Token.

Prefer a one-URL setup?

If your client supports remote connectors (for example Claude web and desktop), you can skip the local install entirely and add Bolti with a single URL and browser sign-in. See Remote Connector. Both paths expose the same tools.

The Bolti server is published to npm as @bolti/mcp. It runs as a standard stdio process, so any MCP-aware client can launch it with a single command. You need Node.js 18 or newer, and a Bolti Personal Access Token (PAT) that starts with mcp_.

Get a token first

Every install below needs a Personal Access Token. Create one in the Bolti dashboard under profile (bottom-left of the sidebar) -> Access Tokens -> Create Token. It is shown only once, so copy it immediately. See Personal Access Tokens for the full walkthrough.

The run command​

The server always runs the same way:

npx -y @bolti/mcp

npx downloads and runs the latest @bolti/mcp without a global install. The -y flag skips the install prompt. The server reads its configuration from environment variables (see Configuration below); the only one you usually need is BOLTI_API_TOKEN.

Claude Code​

Add the server with a single command. Replace mcp_YOUR_TOKEN with your real token:

claude mcp add bolti --env BOLTI_API_TOKEN=mcp_YOUR_TOKEN -- npx -y @bolti/mcp

Restart Claude Code (or start a new session) and the bolti tools become available in chat.

Cursor​

You have two options.

Paste this URL into your browser's address bar and confirm the install in Cursor. Then edit the created config to swap mcp_YOUR_TOKEN for your real token:

cursor://anysphere.cursor-deeplink/mcp/install?name=bolti&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJvbHRpLW1jcCJdLCJlbnYiOnsiQk9MVElfQVBJX1RPS0VOIjoibWNwX1lPVVJfVE9LRU4ifX0=

Manual JSON (Cursor)​

Add the block below to ~/.cursor/mcp.json for all projects, or to a project-local .cursor/mcp.json to scope it to one repository:

{
  "mcpServers": {
    "bolti": {
      "command": "npx",
      "args": ["-y", "@bolti/mcp"],
      "env": { "BOLTI_API_TOKEN": "mcp_YOUR_TOKEN" }
    }
  }
}

Reload Cursor after saving.

Claude Desktop​

Add the same mcpServers block to your claude_desktop_config.json:

{
  "mcpServers": {
    "bolti": {
      "command": "npx",
      "args": ["-y", "@bolti/mcp"],
      "env": { "BOLTI_API_TOKEN": "mcp_YOUR_TOKEN" }
    }
  }
}

Restart Claude Desktop after saving.

Any other MCP client​

The server speaks the standard MCP stdio transport. Configure your client to launch:

npx -y @bolti/mcp

with BOLTI_API_TOKEN set in the process environment. That is all any compliant client needs.

Configuration​

All settings are environment variables. Only BOLTI_API_TOKEN is required (unless you authenticate at runtime with the login_with_token tool).

VariableDefaultPurpose
BOLTI_API_TOKEN(none)Your Personal Access Token, starting with mcp_. Required unless you use login_with_token.
BOLTI_API_BASE_URLhttps://api.bolti.co.inBackend the server talks to. Override only for self-hosted or staging environments.
BOLTI_TOOL_TIMEOUT_MS15000Per-tool timeout for requests to the Bolti backend, in milliseconds.
BOLTI_MAX_PAGE_SIZE100Upper cap on page size for paginated list tools.
BOLTI_DEFAULT_PAGE_SIZE20Default page size when a list tool is called without one.
Legacy variable names

Earlier releases used MCP_* names such as MCP_AUTH_MODE and MCP_BOOTSTRAP_TOKEN. Those two are removed. The remaining MCP_* names still work as fallbacks, but you should configure the BOLTI_* names shown above.

Verify the install​

Once the server is connected, run these three tools from chat in order:

  1. system_health - reports the server version and confirms the Bolti backend is reachable.
  2. whoami - confirms your token authenticated and shows which user and workspace you are acting as.
  3. agents_list - provide workspace_id when your token can access multiple workspaces and no default workspace is configured.

If all three succeed, you are ready to go.

If something fails

A system_health failure usually means Node cannot reach the backend (check BOLTI_API_BASE_URL and your network). A whoami failure means the token is missing, malformed, or revoked - re-check BOLTI_API_TOKEN. See Personal Access Tokens to mint a fresh one.

Where to go next​

If you want to...Read
Understand tokens, scopes, and expiryPersonal Access Tokens
See every tool the server exposesAvailable Tools
Get inspired with concrete promptsUse Cases