MCP

The Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external tools and data. Blue’s MCP server allows AI assistants to read and write data in your Blue workspaces — listing records, creating tasks, managing checklists, and more.

Endpoint

https://mcp.blue.app/mcp

Blue uses the Streamable HTTP transport (the current MCP standard). It works directly with Claude Code, Cursor, Windsurf, and other clients that support remote MCP servers. Claude Desktop only speaks local stdio transport, so its setup below uses the mcp-remote bridge to connect.

Authentication

Blue’s MCP server uses Personal Access Tokens (PATs) for authentication. You’ll need three headers on every request:

Generating a Personal Access Token

1. Log in to Blue
2. Go to Account → API
3. Click Create Token
4. Copy the Token ID and Token Secret — you’ll need both

Setup

Claude Desktop

Add the following to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "blue": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.blue.app/mcp",
        "--header",
        "blue-token-id:YOUR_TOKEN_ID",
        "--header",
        "blue-token-secret:YOUR_TOKEN_SECRET",
        "--header",
        "blue-org-id:YOUR_ORG_SLUG"
      ]
    }
  }
}

Restart Claude Desktop after saving. This uses mcp-remote to bridge the remote MCP server to Claude Desktop’s local transport.

Claude Code

claude mcp add \
  -t http \
  -H "blue-token-id: YOUR_TOKEN_ID" \
  -H "blue-token-secret: YOUR_TOKEN_SECRET" \
  -H "blue-org-id: YOUR_ORG_SLUG" \
  -- blue https://mcp.blue.app/mcp

Restart Claude Code after adding. To verify: claude mcp list. To remove: claude mcp remove blue.

Cursor

Add the following to .cursor/mcp.json in your project directory (or ~/.cursor/mcp.json for global access):

{
  "mcpServers": {
    "blue": {
      "url": "https://mcp.blue.app/mcp",
      "headers": {
        "blue-token-id": "YOUR_TOKEN_ID",
        "blue-token-secret": "YOUR_TOKEN_SECRET",
        "blue-org-id": "YOUR_ORG_SLUG"
      }
    }
  }
}

Or via the UI: Settings → Tools & MCP → Add Server.

Windsurf

Add the following to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "blue": {
      "serverUrl": "https://mcp.blue.app/mcp",
      "headers": {
        "blue-token-id": "YOUR_TOKEN_ID",
        "blue-token-secret": "YOUR_TOKEN_SECRET",
        "blue-org-id": "YOUR_ORG_SLUG"
      }
    }
  }
}

Or via the UI: Plugins → Manage plugins → View raw config.

Other MCP Clients

Any MCP-compatible client that supports the Streamable HTTP transport can connect to Blue. Configure it with:

• URL: https://mcp.blue.app/mcp
• Transport: Streamable HTTP
• Headers: The three authentication headers listed above

Available Tools

Blue’s MCP server provides 51 tools across 21 capability areas, covering records, custom fields, views, reporting, automation, and integrations.

Workspace Scoping

Blue’s data is organised as Organisation → Workspaces → Lists → Records.

• Your organisation is set globally via the blue-org-id header when you configure the MCP connection
• Workspace is passed as a parameter on tools that need it — most write tools and several read tools require a workspace ID
• Read-only tools like get-record only need the entity ID — the workspace is resolved automatically

This means your AI assistant can work across multiple workspaces in a single conversation.

Examples

Here are some things you can ask your AI assistant once Blue is connected:

Reading data:

• “List my workspaces”
• “Show me the open records in the Sales workspace”
• “Get the details of record [ID]”
• “How many records are overdue?”
• “What custom fields are set up in the Onboarding workspace?”

Writing data:

• “Create a record called ‘Follow up with client’ in the Sales workspace”
• “Mark that record as done”
• “Move it to the Completed list”
• “Add a checklist with three items: send proposal, schedule call, get signature”
• “Tag it as ‘urgent’”
• “Add a comment: ‘Discussed in today’s meeting, needs follow-up by Friday’”

Rate Limits

MCP requests are rate-limited to 60 requests per minute per user. This is more than sufficient for interactive AI assistant usage.

Security

• All requests are authenticated with your Personal Access Token
• Tokens respect the same permissions as your user account — MCP tools can only access data you have access to
• All communication uses HTTPS with TLS encryption
• Blue’s MCP server runs on the same infrastructure as the main API with the same security controls