> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ev-cloud.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ev-cloud.ai/_mcp/server.

# MCP server

EV Cloud serves the [Model Context Protocol](https://modelcontextprotocol.io) at `/mcp` on your EV Cloud host. Every operation in the [API Reference](/api-reference) is a tool, named after its operation, such as `cpo_locations_list` or `emsp_tokens_suspend`. Health checks are left out.

```text
https://api.ev-cloud.ai/mcp
```

The transport is streamable HTTP.

## Connect

You only need the URL. On the first call, your client opens your browser: sign in with your OCPPLab account, choose the organization and select **Allow**. The client stores and refreshes its own access.

**`Claude Code`**

```bash Claude Code
claude mcp add --transport http evcloud https://api.ev-cloud.ai/mcp
```

**`Cursor (.cursor/mcp.json)`**

```json Cursor (.cursor/mcp.json)
{
  "mcpServers": {
    "evcloud": { "url": "https://api.ev-cloud.ai/mcp" }
  }
}
```

**`VS Code (.vscode/mcp.json)`**

```json VS Code (.vscode/mcp.json)
{
  "servers": {
    "evcloud": { "type": "http", "url": "https://api.ev-cloud.ai/mcp" }
  }
}
```

For Claude Desktop and claude.ai, add a custom connector with the same URL.

### With an SDK token instead

For agents that run without a browser, such as CI, send an SDK token that expires in the `Authorization` header:

```json
{
  "mcpServers": {
    "evcloud": {
      "url": "https://api.ev-cloud.ai/mcp",
      "headers": { "Authorization": "Bearer ${EVCLOUD_TOKEN}" }
    }
  }
}
```

## How sign-in works

`/mcp` follows the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization):

1. A call without a token gets `401` with `WWW-Authenticate: Bearer resource_metadata="https://api.ev-cloud.ai/.well-known/oauth-protected-resource/mcp"`.
2. That document names the OCPPLab sign-in server. The client registers itself there and signs you in with OAuth 2.1 and PKCE.
3. The client sends the access token on every call. EV Cloud checks it the same way it checks REST requests.

The CLI's `evcloud-cli auth login` uses the same sign-in server. See [Authentication](/get-started/authentication).

## What a tool call can do

A tool call runs the matching API operation as you, so the same rules apply:

* **Organization:** results are scoped to the organization you chose at sign-in.
* **Role:** admin-only operations return `403` unless you are an organization admin.
* **Rate limits:** the same per-organization limits as the REST API.

Tools that only read are marked read-only, and `DELETE` operations are marked destructive, so your client can ask before running them. Every other tool changes data: review what the agent sends.

> **Warning**
>
> An agent with EV Cloud tools can change your charging infrastructure, such as rebooting chargers or revoking driver tokens. Approve tool calls you have not checked.

## Try it locally

Run the API from the evcloud-sdk repo, then open the MCP Inspector on it:

```bash
uv run evcloud
make mcp-inspect
```

## Host it

Set these on the EV Cloud API deployment to turn on browser sign-in:

| Variable           | Value                                                                                                       |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| `MCP_OAUTH_ISSUER` | The issuer of the OAuth access tokens: the `iss` claim, such as `https://<project-ref>.supabase.co/auth/v1` |
| `MCP_PUBLIC_URL`   | The public origin of the API, such as `https://api.ev-cloud.ai`                                             |

Without them, `/mcp` accepts SDK tokens only. With `MCP_OAUTH_ISSUER` but no `MCP_PUBLIC_URL`, it accepts OAuth tokens but clients cannot discover where to sign in. `/mcp` is stateless, so any replica serves any call.

The sign-in server must have OAuth 2.1 and dynamic client registration turned on, and its access token hook must add `org_id`, `evcloud_role` and `aud: "evcloud-mcp"` to OAuth tokens.