MCP server | EV Cloud Docs

EV Cloud serves the Model Context Protocol at /mcp on your EV Cloud host. Every operation in the API Reference is a tool, named after its operation, such as cpo_locations_list or emsp_tokens_suspend. Health checks are left out.

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 mcp add --transport http evcloud 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:

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

/mcp follows the MCP authorization spec:

A call without a token gets 401 with WWW-Authenticate: Bearer resource_metadata="https://api.ev-cloud.ai/.well-known/oauth-protected-resource/mcp".
That document names the OCPPLab sign-in server. The client registers itself there and signs you in with OAuth 2.1 and PKCE.
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.

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.

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:

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.