bluenexus.ai Get API Key

Generic MCP Client

This guide covers the protocol-level details for connecting any MCP client to BlueNexus. If you're building a custom MCP client or debugging an integration, this is the reference you need.

Endpoint

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

Protocol: JSON-RPC 2.0 over Streamable HTTP (POST) Auth: Bearer token in the Authorization header Rate Limit: 30 requests/minute

Authentication

See How MCP Auth Works for the full OAuth flow. For quick testing, use a Personal Access Token:

Authorization: Bearer YOUR_PAT

JSON-RPC Methods

initialize

Initialize the MCP session:

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

tools/list

Discover available tools:

{
  "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...",
        "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...",
        "inputSchema": {
          "type": "object",
          "properties": {}
        }
      },
      {
        "name": "add-to-knowledge-base",
        "description": "Add a document to the user's knowledge base...",
        "inputSchema": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "content": { "type": "string" },
            "source_type": { "type": "string", "enum": ["text", "url"] },
            "url": { "type": "string" }
          },
          "required": ["name", "content"]
        }
      },
      {
        "name": "search-knowledge-base",
        "description": "Search and read the user's knowledge base wiki...",
        "inputSchema": {
          "type": "object",
          "properties": {
            "action": { "type": "string", "enum": ["search", "get_page", "get_index"] },
            "query": { "type": "string" },
            "slug": { "type": "string" }
          },
          "required": ["action"]
        }
      }
    ]
  }
}

tools/call — use-agent

Execute the agent with a prompt:

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

The connector parameter is optional — it hints which service to use. If omitted, the agent auto-detects the right service from the prompt.

The _meta.progressToken enables progress notifications during long-running agent executions (SSE mode only).

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\n3. 1:1 with Sarah - 4:00 PM"
      }
    ]
  }
}

tools/call — list-connections

List the user's connected services:

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

Response includes a text summary and structured metadata:

{
  "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-123",
          "serviceLabel": "Google Workspace",
          "connectedUserAccount": {
            "email": "user@gmail.com",
            "displayName": "John Doe"
          }
        }
      ]
    }
  }
}

tools/call — search-knowledge-base

Search the user's compiled knowledge wiki:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search-knowledge-base",
    "arguments": {
      "action": "search",
      "query": "pricing plans"
    }
  },
  "id": "5"
}

Read a specific wiki page:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search-knowledge-base",
    "arguments": {
      "action": "get_page",
      "slug": "pricing-policy"
    }
  },
  "id": "6"
}

Get the table of contents:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search-knowledge-base",
    "arguments": {
      "action": "get_index"
    }
  },
  "id": "7"
}

tools/call — add-to-knowledge-base

Add a document to the knowledge base:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "add-to-knowledge-base",
    "arguments": {
      "name": "Meeting Notes — April 15",
      "content": "# Meeting Notes\n\n## Decisions\n- Launch date set for Q3..."
    }
  },
  "id": "8"
}

Requires universal-mcp-read-write scope. The document will be automatically compiled into wiki pages.

Response Format

BlueNexus supports two response formats:

JSON (Single Response)

Accept: application/json

Or use the header:

X-Response-Format: json

Returns a single JSON-RPC response object.

SSE (Streaming)

Accept: application/json, text/event-stream

Or use the header:

X-Response-Format: sse

Returns a Server-Sent Events stream with progress notifications during agent execution:

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

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

SSE is recommended for long-running use-agent calls where you want to show progress to the user.

Custom Headers

Header Description
X-Response-Format json or sse — overrides the Accept header
X-LLM-Model Override the LLM model used by the agent (e.g., bluenexus/glm-4.7-flash-tee)

Error Handling

MCP errors are returned as JSON-RPC error responses:

{
  "jsonrpc": "2.0",
  "id": "3",
  "error": {
    "code": -32000,
    "message": "Authentication required. Please provide a valid Bearer token."
  }
}

HTTP-level errors:

  • 401 — Missing or invalid Bearer token
  • 402 — Insufficient credits
  • 429 — Rate limit exceeded (30 req/min)
  • 406 — Client must accept both application/json and text/event-stream

Next Steps