MCP

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data. The Blue MCP server lets assistants read and change workspace data, including records and checklists.

Transport

The server uses Streamable HTTP. Claude Code, Cursor, Windsurf, and other remote MCP clients can connect directly. Claude Desktop uses the mcp-remote bridge for its local stdio transport.

Blue-hosted endpoint

Use this endpoint for Blue-hosted accounts. For another deployment, confirm the MCP endpoint and availability with its operator.

https://mcp.blue.app/mcp

Authentication

The Blue MCP server uses Personal Access Tokens (PATs). Send these three headers with every request:

Generate a Personal Access Token

1. Log in to Blue.
2. Open Account > API.
3. Select Create Token.
4. Copy the Token ID and Token Secret.

Configure an MCP client

1. Choose a client that supports the server transport, or use the local bridge described above.
2. Enter the MCP endpoint for your deployment.
3. Add the three authentication headers from Authentication. Keep their names unchanged.
4. Save the configuration and restart the client when required.
5. Run a read request, such as listing your workspaces, to confirm access.

Blue-hosted client examples

These examples retain the Blue-hosted endpoint and the blue configuration name. For a different deployment, use its endpoint. Header names and tool identifiers remain the same.

Claude Desktop

Add this configuration to the 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"
      ]
    }
  }
}

Save the file and restart Claude Desktop. The mcp-remote package bridges the remote MCP server to the local Claude Desktop 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 you add the server. Run claude mcp list to verify the connection. Run claude mcp remove blue to remove it.

Cursor

Add this configuration to .cursor/mcp.json in your project directory. For global access, add it to ~/.cursor/mcp.json.

{
  "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"
      }
    }
  }
}

You can also open Settings > Tools & MCP > Add Server.

Windsurf

Add this configuration 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"
      }
    }
  }
}

You can also open Plugins > Manage plugins > View raw config.

Other MCP clients

Configure any MCP client that supports Streamable HTTP with:

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

Available tools

The Blue MCP server provides 53 tools across 21 capability areas. These tools cover records, custom fields, views, reports, automations, and integrations.

invite-user-to-workspace returns requestedAccessLevel. The effective level can differ: organization owners join a workspace as ADMIN, and an existing invitation keeps its stored level when it is resent.

Workspace scoping

The product hierarchy is Organization > Workspaces > Databases > Records. Tool and parameter names retain their API identifiers, including names that contain list or tag.

• Set the organization globally with the blue-org-id header.
• Pass a workspace parameter to tools that require it. Most write tools and several read tools require a workspace ID.
• For read-only tools such as get-record, pass only the entity ID. Blue resolves the workspace automatically.

An assistant can work across multiple workspaces in one conversation.

Examples

After you connect Blue, you can use requests such as:

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”
• “Assign the proposal item to Maria and make it due Friday at 15:00”
• “Tag it as ‘urgent’”
• “Add a comment: ‘Discussed in today’s meeting, needs follow-up by Friday’”

Rate limits

Blue limits MCP requests to 60 requests per minute for each user.

Security

• Blue authenticates every request with your Personal Access Token.
• The token has the same permissions as your user account. MCP tools can access only data available to your account.
• All communication uses HTTPS with TLS encryption.

Blue-hosted infrastructure

The Blue-hosted MCP server uses the same infrastructure and security controls as the Blue-hosted API. For another deployment, use the hosting and security information supplied by its operator.