> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.cxplanner.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# MCP Server - Connect with you LLM

## Overview: MCP server

The MCP server exposes CxPlanner tools over streamable HTTP using the same authentication model as the REST API, which is used when you want an LLM or automation client to call structured tools instead of raw REST endpoints. CxPlanner runs a separate MCP endpoint per data region - see the endpoints below.

For creating API credentials, see [Set up API access](https://help.cxplanner.com/en-us/article/set-up-api-access-sljl5q/).

* Your role must be company **Admin** to configure or test MCP connections.
* Use the endpoint that matches the region your CxPlanner project is hosted in - see the table below.
* This lets clients call MCP tools. It does not change project data unless a tool performs a write action allowed by your token.

|| Only users with the company role **Admin** can configure or test MCP connections.

**MCP server endpoints**

| Region | Endpoint |
| ---- |
| EU | https://mcp.cxplanner.com (also reachable at `https://origin-eu-mcp.cxplanner.com`) |
| US | https://origin-us-mcp.cxplanner.com |

|| Connecting to the wrong region's endpoint will not work for a project hosted in the other region - confirm which region your project is in before configuring a client.

Authentication uses the same Bearer token and projectID rules as the REST API. Rate limits match REST. A `Mcp-Session-Id` is issued on `initialize` and must be echoed by the client. Project-aware tools may require a `projectID` parameter.

## How to connect to the MCP server

1. Set the base endpoint to your region's MCP endpoint (see the table above).
2. Authenticate with the same Bearer token and projectID used for REST.
3. Call `initialize` and capture the `Mcp-Session-Id`.
4. Call `tools/list` to confirm available tools.
5. Call a tool with `tools/call`.
6. Test with `ping` and arguments `{ "message": "hello" }`.

Examples:

* Global API tool: `get_users_on_platform` (no parameters)
* Project API tool: `get_users` (requires `projectID`)

## Results: MCP tools

| Tool | Purpose |
| ---- |
| initialize | Starts a session and returns a session ID |
| tools/list | Lists available tools |
| tools/call | Executes a specific tool |
| ping | Tests connectivity with a message response |

## Troubleshooting: MCP server

| Problem | Cause | Solution |
| ---- |
| 401 Unauthorized | Missing or invalid Bearer token | Check the token, include projectID when required, and retry |
| Tool not found | Incorrect tool name | Call `tools/list` and use an exact tool name from the response |
| Request rate limited | Same REST rate limit applied to MCP | Slow down calls or batch requests |
| No session ID returned | `initialize` was not completed | Run `initialize` first, then send `Mcp-Session-Id` on later calls |

## Example code

```javascript
const endpoint = 'https://mcp.cxplanner.com'; // EU. For a US-hosted project, use https://origin-us-mcp.cxplanner.com

async function mcp(method, params = {}, id = String(Date.now())) {
  const res = await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method,
      params,
      id,
    }),
  });

  if (!res.ok) {
    const text = await res.text().catch(() => '');
    throw new Error(`HTTP ${res.status} ${res.statusText}: ${text}`);
  }

  return res.json();
}

// Example: initialize
(async () => {
  try {
    const resp = await mcp('initialize');
    console.log('initialize →', resp);
  } catch (err) {
    console.error(err);
  }
})();

// Example: list tools
(async () => {
  try {
    const resp = await mcp('tools/list');
    console.log('tools/list →', resp);
  } catch (err) {
    console.error(err);
  }
})();

// Example: call tool
(async () => {
  try {
    const resp = await mcp('tools/call', { name: 'get_users_on_platform', arguments: { bearerToken: 'xxxxx' } });
    console.log('tools/call →', resp);
  } catch (err) {
    console.error(err);
  }
})();
```