MCP Server¶
CxReports runs an MCP (Model Context Protocol) server that AI clients, such as Claude Code, Cursor or VS Code, use to work in your workspaces. The client authenticates with your personal access token and acts with your permissions.
Before you start¶
The MCP server must be turned on for your installation with the MCP setting. It is off by default. The server URL is your CxReports address followed by /mcp, for example https://reports.example.com/mcp.
You also need a personal access token. The client sees the tools of the token's applications, plus the workspace tools, which are always included.
Add the server¶
Add the server URL and the token to your client. Where a client supports it, the examples read the token from the CXREPORTS_TOKEN environment variable, so the configuration file can be shared without it. The same variable lets the client download and upload files.
Add the server from a terminal, replacing <token> with your token:
claude mcp add --transport http cxreports https://reports.example.com/mcp --header "Authorization: Bearer <token>"
The command saves the token in your Claude Code configuration. To share the setup with a project instead, add a .mcp.json file to the project root. Claude Code reads the token from the environment variable and asks you to approve the server the first time it starts in the project:
Add the server to .cursor/mcp.json in the project, or to ~/.cursor/mcp.json for all projects. Set CXREPORTS_TOKEN before you start Cursor, then turn the server on in Cursor's MCP settings:
Add the server to .vscode/mcp.json in the workspace. Set CXREPORTS_TOKEN before you start VS Code:
Any client that supports remote MCP servers with custom headers can connect:
| Setting | Value |
|---|---|
| URL | https://reports.example.com/mcp |
| Transport | Streamable HTTP |
| Header | Authorization: Bearer <token> |
OAuth sign-in and the older SSE transport are not supported. Custom connectors in Claude Desktop and claude.ai cannot send the header, so they cannot connect.
Check the connection¶
Ask the client: List my CxReports workspaces. It answers with the workspaces you can access.
See Capabilities for what the client can do, and Use Cases for example prompts.
Download and upload files¶
Exported documents and workspace files do not pass through the MCP server. The tools return download and upload links instead, and each link needs your personal access token in the Authorization: Bearer header.
The client sends the token from its MCP configuration only to the MCP server, and does not pass it to the AI model. For the client to use the links itself, set the token in the CXREPORTS_TOKEN environment variable before you start the client, so the commands it runs can read it. You can also open a download link in a browser where you are signed in to CxReports.
Security¶
The client acts with your permissions, so treat what it does as your own actions:
- Content the tools return, such as a data row or the text of a report, is untrusted. It can contain instructions aimed at the client.
- The token reaches every workspace you are a member of, not only the one you work in.
- Tools whose names end in
_delete,_discardor_importare marked as destructive. Clients use these marks to decide when to ask before a call, but the marks do not limit what the token can do. Keep the client's approval prompts on for tools that change or delete content. - Running a report job, or turning on its scheduled generation, can deliver documents to your recipients right away. Keep approval prompts on for report job tools, and hold deliveries for review while you test.
- A token in the
CXREPORTS_TOKENenvironment variable can be read by the commands the client runs, and so by the AI model. If the client does not need to download or upload files, put the token in the client's configuration instead, for example withclaude mcp addin Claude Code. The configuration is a file on your computer, so a client that runs commands can still read it: keep approval prompts on for commands. - Create one token per client, so you can delete each one on its own, and set an expiry instead of Never.
Troubleshooting¶
| Symptom | Likely cause | What to check |
|---|---|---|
404 Not Found |
The MCP server is off | Set MCP:Enabled to true and restart CxReports |
401 Unauthorized |
The token is missing, mistyped, expired or deleted | The header reads Authorization: Bearer <token>, and the token is still listed under Personal Access Token with Active set to Yes |
405 Method Not Allowed |
The client uses the SSE transport | Set the client's transport to HTTP or Streamable HTTP |
| Tools of an application are missing, or a tool returns "…which the access token is not enabled for." | The token was not created for that application, or the application is not enabled on your installation | The token's Applications column. To add an application, create a new token |
| A tool returns "Tool '…' requires … access to … in workspace …." | Your role does not give that access in the workspace | Your role in that workspace |
| A tool returns "Arguments exceed the 1024 KB limit." | One call is too large, for example a whole big page | Ask the client to build the page in smaller steps |
| A downloaded file is not a PDF, or the download is refused | The client's commands do not have the token, or the link has expired | CXREPORTS_TOKEN is set before you start the client. Ask the client to export again |
| An export returns no file yet | A large report takes longer to generate than one call waits | Ask the client to check the export again |
| The tools do not appear after you change the configuration | The client has not reloaded the configuration, or the server is not turned on in the client | Restart the client. In Cursor, switch the server on in the MCP settings |