# MCP server

The CSPR.cloud MCP server lets AI agents connect to CSPR.cloud through the Model Context Protocol. Use it when your agent supports remote MCP servers and you want it to call CSPR.cloud tools directly.

## Community project

The hosted MCP server is based on the community Casper MCP server. The source repository is available at [github.com/msanlisavas/casper-mcp](https://github.com/msanlisavas/casper-mcp).

## Endpoints

| Network | MCP endpoint                         |
| ------- | ------------------------------------ |
| Mainnet | `https://mcp.cspr.cloud/mcp`         |
| Testnet | `https://mcp.testnet.cspr.cloud/mcp` |

## API key

The hosted MCP server requires a CSPR.cloud API key. Store it in an environment variable and do not commit it to source control.

```bash
export CSPR_CLOUD_API_KEY="your-api-key"
```

## Codex setup

Codex stores MCP server configuration in `~/.codex/config.toml`. You can add the server with the CLI and then update the configuration to pass the API key as an HTTP header.

### 1. Add the MCP server

For Mainnet:

```bash
codex mcp add cspr_cloud --url https://mcp.cspr.cloud/mcp
```

For Testnet:

```bash
codex mcp add cspr_cloud_testnet --url https://mcp.testnet.cspr.cloud/mcp
```

### 2. Add the API-key header

Open `~/.codex/config.toml` and add `env_http_headers` to the CSPR.cloud MCP server entry.

Mainnet:

```toml
[mcp_servers.cspr_cloud]
url = "https://mcp.cspr.cloud/mcp"
env_http_headers = { "X-CSPR-Cloud-Api-Key" = "CSPR_CLOUD_API_KEY" }
```

Testnet:

```toml
[mcp_servers.cspr_cloud_testnet]
url = "https://mcp.testnet.cspr.cloud/mcp"
env_http_headers = { "X-CSPR-Cloud-Api-Key" = "CSPR_CLOUD_API_KEY" }
```

`env_http_headers` maps the HTTP header name to the environment variable that contains the value. In the example above, Codex reads `CSPR_CLOUD_API_KEY` and sends it as `X-CSPR-Cloud-Api-Key`.

### 3. Verify the connection

Start a new Codex session and run:

```
/mcp
```

The CSPR.cloud MCP server should appear in the active MCP servers list. If it does not, check that `CSPR_CLOUD_API_KEY` is exported in the shell where Codex is started and that the server entry is enabled in `~/.codex/config.toml`.

## Claude Code setup

Claude Code supports remote MCP servers over HTTP. Use `claude mcp add-json` so the API key can stay in the `CSPR_CLOUD_API_KEY` environment variable instead of being written directly into Claude configuration.

Claude Code supports multiple MCP scopes:

* `local` - available only in the current project. This is the default.
* `project` - shared through a `.mcp.json` file in the project root.
* `user` - available across all projects for the current user.

The examples below use `--scope project`, which writes a shareable `.mcp.json` file with an environment-variable placeholder instead of the API key. Claude Code asks you to approve project-scoped MCP servers before using them.

### 1. Add the MCP server

For Mainnet:

```bash
claude mcp add-json cspr_cloud --scope project \
  '{"type":"http","url":"https://mcp.cspr.cloud/mcp","headers":{"X-CSPR-Cloud-Api-Key":"${CSPR_CLOUD_API_KEY}"}}'
```

For Testnet:

```bash
claude mcp add-json cspr_cloud_testnet --scope project \
  '{"type":"http","url":"https://mcp.testnet.cspr.cloud/mcp","headers":{"X-CSPR-Cloud-Api-Key":"${CSPR_CLOUD_API_KEY}"}}'
```

Claude Code expands `${CSPR_CLOUD_API_KEY}` from the environment when it loads the MCP server. Start Claude Code from a shell where the variable is exported.

### 2. Verify the connection

From a terminal:

```bash
claude mcp list
```

Inside Claude Code:

```
/mcp
```

The CSPR.cloud MCP server should appear in the MCP servers list. If Claude reports a configuration parsing error, check that `CSPR_CLOUD_API_KEY` is set in the shell where Claude Code starts.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cspr.cloud/agentic-tools/mcp-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.