MCP Endpoint

The Universal MCP endpoint implements the Model Context Protocol, allowing any MCP-compatible client to access users' connected services through BlueNexus.

Endpoint

POST https://api.bluenexus.ai/mcp

Property	Value
Protocol	JSON-RPC 2.0 over Streamable HTTP
Authentication	Bearer token (`Authorization: Bearer <token>`)
Required Scopes	`universal-mcp-read` or `universal-mcp-read-write`
Rate Limit	30 requests per minute
Credit Guard	Requires positive credit balance (returns 402 if exhausted)

Knowledge base restrictions: If the token's session has allowedKnowledgeBaseIds set, knowledge-base MCP tools (read and write) are blocked for any KB outside that list, even if the token holds the universal-mcp-read-write scope. See Scopes and Permissions for details.

Request Format

All requests use the JSON-RPC 2.0 format:

{
  "jsonrpc": "2.0",
  "method": "<method>",
  "params": {},
  "id": "<request-id>"
}

Supported Methods

Method	Description	Required Scope
`initialize`	Initialize MCP session	`universal-mcp-read`
`tools/list`	List available tools	`universal-mcp-read`
`tools/call`	Execute a tool	`universal-mcp-read-write`

Response Format

JSON Response

Request with:

Accept: application/json

Or:

X-Response-Format: json

Returns a single JSON-RPC response body.

SSE Streaming Response

Request with:

Accept: application/json, text/event-stream

Or:

X-Response-Format: sse

Returns Server-Sent Events. Each event has data: prefix with a JSON-RPC object. Includes progress notifications during long-running tool executions.

event: message
data: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"...","progress":0.5,"total":1}}

event: message
data: {"jsonrpc":"2.0","id":"1","result":{"content":[{"type":"text","text":"..."}]}}

Custom Headers

Header	Type	Description
`Authorization`	Required	`Bearer <access_token>`
`X-Response-Format`	Optional	`json` or `sse` — overrides Accept header
`X-LLM-Model`	Optional	Override the LLM model for this request

Methods

initialize

Initialize the MCP session.

Request:

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "my-app",
      "version": "1.0.0"
    }
  },
  "id": "1"
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "bluenexus-mcp",
      "version": "1.0.0"
    }
  }
}

tools/list

List available tools.

Request:

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {},
  "id": "2"
}

Response:

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "tools": [
      {
        "name": "use-agent",
        "description": "An agent that can access and use the user's connected services.\n\nThe agent can help you:\n- Access the user's data across connected services\n- Perform actions like creating issues, sending messages, scheduling meetings\n- Coordinate tasks that span multiple services\n- Process complex requests and return the most relevant information\n\nUse the 'list-connections' tool to see which services are available.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "prompt": {
              "type": "string",
              "description": "The prompt/instruction for the agent"
            },
            "connector": {
              "type": "string",
              "description": "Optional: Filter to a specific connector/provider (e.g., 'github', 'notion', 'slack')"
            }
          },
          "required": ["prompt"]
        }
      },
      {
        "name": "list-connections",
        "description": "List all the active connections of the user.\n\nReturns information about:\n- Which service/connector is active (e.g., GitHub, Google, Slack)\n- With which account the user is active\n\nUse this to discover what services are available before using the BlueNexus agent.",
        "inputSchema": {
          "type": "object",
          "properties": {}
        }
      }
    ]
  }
}

tools/call — use-agent

Execute the AI agent with a prompt. The agent identifies the appropriate connected service, makes API calls, and returns the result.

Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "use-agent",
    "arguments": {
      "prompt": "What's on my Google Calendar today?",
      "connector": "google"
    },
    "_meta": {
      "progressToken": "progress-1"
    }
  },
  "id": "3"
}

Parameters:

Parameter	Type	Required	Description
`prompt`	string	Yes	The instruction for the agent
`connector`	string	No	Filter to a specific connector (e.g., `"github"`, `"slack"`, `"notion"`)

Response:

{
  "jsonrpc": "2.0",
  "id": "3",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Here are your Google Calendar events for today:\n\n1. Team Standup - 9:00 AM\n2. Product Review - 2:00 PM"
      }
    ]
  }
}

Behavior:

The agent uses a ReAct (Reasoning + Acting) pattern to determine which tools and services to invoke
Responses are sanitized: sensitive tokens are redacted, output is truncated to 50KB
Prompt injection detection blocks malicious inputs
Credits are consumed based on LLM token usage

Errors:

McpToolUnauthorizedError — No valid authentication
McpToolInsufficientCreditsError — Credit balance too low
McpToolPromptInjectionBlockedError — Prompt injection detected
McpToolAgentExecutionError — Agent execution failed

tools/call — list-connections

List the user's active service connections.

Request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list-connections",
    "arguments": {}
  },
  "id": "4"
}

Response:

{
  "jsonrpc": "2.0",
  "id": "4",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Active connections:\n- Google Workspace (user@gmail.com)\n- Slack (user@company.com)\n- GitHub (username)"
      }
    ],
    "_meta": {
      "active": [
        {
          "serviceId": "conn-abc123",
          "serviceLabel": "Google Workspace",
          "connectedUserAccount": {
            "email": "user@gmail.com",
            "displayName": "John Doe"
          }
        }
      ]
    }
  }
}

OAuth Discovery (RFC 9728)

MCP clients that don't have a pre-configured token discover authentication through the standard well-known endpoints:

POST /mcp without token → 401 with WWW-Authenticate: Bearer resource_metadata="https://api.bluenexus.ai/.well-known/oauth-protected-resource"
Fetch /.well-known/oauth-protected-resource → discover authorization server URL
Fetch /.well-known/oauth-authorization-server → discover endpoints (register, authorize, token)
POST /v1/auth/register (DCR) → get client_id
PKCE OAuth flow → get Bearer token
Retry POST /mcp with token

See How MCP Auth Works for the complete flow.

HTTP Error Responses

Status	Error	Description
401	`UnauthorizedError`	Missing or invalid Bearer token
402	`CreditsExhaustedError`	Insufficient credit balance
406	`NotAcceptableError`	Client must accept both `application/json` and `text/event-stream`
429	`TooManyRequestsError`	Rate limit exceeded (30 req/min)

Error body format:

{
  "error": "UnauthorizedError",
  "message": "Authentication required. Please provide a valid Bearer token.",
  "statusCode": 401
}

Curl Examples

List tools:

curl -X POST https://api.bluenexus.ai/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Response-Format: json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":"1"}'

Call use-agent:

curl -X POST https://api.bluenexus.ai/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Response-Format: json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"use-agent","arguments":{"prompt":"What meetings do I have today?"}},"id":"2"}'

Call list-connections:

curl -X POST https://api.bluenexus.ai/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Response-Format: json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list-connections","arguments":{}},"id":"3"}'