MCP Server Reference

For: Customers who want an AI assistant (Claude Desktop, Claude Code, or any MCP client) to manage Axemere directly, reading spend, managing credentials, reviewing approvals, via natural language instead of writing API calls.

Axemere exposes a remote Model Context Protocol server covering the same operations as the Management API, with one deliberate exception: minting and revoking API keys stays REST-only (see Keys below). Every tool call is authenticated and scope-checked exactly like the REST API: the MCP server is a thin transport over the same handlers, not a separate permission model.

Table of Contents

• Transport
• Authentication
• Session Management
• Claude Desktop Configuration
• Tools
  • Records
  • Credentials
  • Providers
  • Workloads
  • Projects
  • Policies
  • Rate Limits
  • Approvals and Quarantine
  • Spend and Dashboard
  • Nodes
  • Attribution
  • SIEM Export Destinations
  • Provider Pricing
  • Alert Channels
  • Alert Subscriptions
  • Budget Limits
  • Org Defaults
  • Keys
• Resources
• Self-Hosted Mode

Transport

Streamable HTTP, per the MCP spec's 2025-03-26 transport revision.

Endpoint: https://us.api.axemere.ai/mcp

A single POST to this endpoint carries all MCP protocol messages (initialize, tool calls, resource reads). There is no separate SSE endpoint to configure.

Authentication

Authorization: Bearer mcpk_<random>

Navigation: Create an MCP key at console.axemere.ai/automation → MCP Server tab, choosing kind mcp, or via POST /mgmt/v1/keys with "kind": "mcp".

See the Management API's key format note for the exact key shape. Like mgk_ keys, an mcpk_ key is created with one of two access levels: Read (["read"]) or Read + Write (["read", "write"]); there is no write-only key. A tool call requiring a scope the key doesn't have returns the same insufficient_scope error as the REST API, surfaced as a tool error. See Keys for the full scope model.

mgk_ and mcpk_ keys are not interchangeable by design: an mgk_ key is rejected by the /mcp endpoint and vice versa. This keeps a compromised MCP client config from also granting direct REST API access, and lets you revoke one surface without affecting the other.

Session Management

The server is stateful per MCP session. After initialize, the response includes an Mcp-Session-Id header: send it back on every subsequent request in the same session. Sessions idle out after 1 hour of inactivity; a client should re-initialize after an invalid_session error rather than treating it as fatal.

Constraint: session state is held in-memory on a single Cloud Run instance. Under autoscaling, a long-idle session that gets routed to a new instance on its next request will see invalid_session and must re-initialize. This is transparent in Claude Desktop and Claude Code, which re-initialize automatically, but matters if you're writing a custom MCP client.

Claude Desktop Configuration

Claude Desktop connects to remote MCP servers via claude_desktop_config.json:

{
  "mcpServers": {
    "axemere": {
      "type": "http",
      "url": "https://us.api.axemere.ai/mcp",
      "headers": {
        "Authorization": "Bearer mcpk_k3jmP9xQ2vT7bN5wL8hR4dF6sA1cE0gU3iY9oZ2mX7q"
      }
    }
  }
}

Restart Claude Desktop after editing this file. Confirm the connection by asking Claude to "list my Axemere credentials": a successful response confirms the key and transport are both working.

Tools

All tools are read-scoped unless marked write. A tool call against a key lacking the required scope returns an MCP tool error with the same insufficient_scope semantics as the REST API.

Records

REST equivalent: Records.

Credentials

REST equivalent: Credentials.

Providers

REST equivalent: Providers and Custom Connectors (BYOC).

Workloads

REST equivalent: Workloads.

Projects

REST equivalent: Projects.

Policies

REST equivalent: Policies.

Rate Limits

REST equivalent: Rate Limits.

Approvals and Quarantine

REST equivalent: Approvals and Quarantine.

Spend and Dashboard

REST equivalent: Spend and Billing and Dashboard and Gateway Health.

Nodes

REST equivalent: Dashboard and Gateway Health.

Attribution

REST equivalent: Attribution.

SIEM Export Destinations

REST equivalent: SIEM Export Destinations.

Provider Pricing

REST equivalent: Provider Pricing.

Read-only, on both REST and MCP. provider_pricing is a single global table shared across every org on the managed fleet, not a per-org resource, so pricing writes are restricted to NOC operators via cert-gated admin routes; there is no write tool on MCP and no write endpoint on REST. See Provider Pricing for the full rationale.

Alert Channels

REST equivalent: Budget Alert Channels.

config.webhook_url (Slack, Teams, Google Chat, Discord channels) is a secret: list_alert_channels and get_alert_channel return it masked as "••••••••", the same convention used for credential secret_ref. It's never returned unmasked after creation, so retain your own copy of the webhook URL. config.to_addresses (the email kind) is not a secret and is never masked. update_alert_channel only changes fields present in the request: to change just the name or enabled state, omit config entirely rather than passing back a masked value, which would overwrite the real stored URL.

Alert Subscriptions

REST equivalent: Budget Alert Subscriptions.

Budget Limits

REST equivalent: Budget Limits and Org Budget Config.

Org Defaults

REST equivalent: Org Defaults.

Keys

REST equivalent: Keys — the full read/write surface; MCP is list-only here (see below).

Key mutation is deliberately excluded from MCP. This is the one place MCP does not mirror the Management API: there is no create_key or revoke_key tool, on any scope. Key records also live on the control plane rather than the gateway the MCP server's other tool handlers talk to, so list_keys doesn't proxy real metadata either: it intentionally returns only a pointer to the REST endpoint (GET /mgmt/v1/keys).

This is a security boundary, not a gap to be closed: an MCP-scoped key that could mint or revoke keys could mint itself broader access, or revoke the very key restricting it: self-escalation and self-revocation. Keeping key creation and revocation REST-only means an MCP client can never be tricked (via prompt injection or a malicious tool result) into minting a new key or revoking an existing one. Ask your assistant to hit the Management API directly (or use curl) for actual key listings, creation, or revocation.

Resources

Resources are read-only, cacheable snapshots an MCP client can attach to context without an explicit tool call, useful for grounding a conversation ("here's our current provider setup") before asking the assistant to act.

Self-Hosted Mode

Self-hosted customers run the MCP server as a standalone binary, mvgc-mcp, against their own gateway: no dependency on Axemere's hosted /mcp endpoint.

# stdio transport (Claude Desktop local server config): the default when --listen is omitted
mvgc-mcp --gateway-url=http://localhost:8080 --admin-token=$MVGC_ADMIN_TOKEN

# or, using a management key instead of the gateway admin token
mvgc-mcp --gateway-url=http://localhost:8080 --mgk=$MVGC_MGK

# HTTP transport, for a remote client: setting --listen switches modes
mvgc-mcp --gateway-url=http://localhost:8080 --mgk=$MVGC_MGK --listen=:8443 \
  --tls-cert=cert.pem --tls-key=key.pem

--admin-token (or MVGC_ADMIN_TOKEN) grants full local access without provisioning a management key, convenient for a single-operator self-hosted install. --mgk= (or MVGC_MGK) is the better choice once more than one person or automation needs access; note that in self-hosted mode the binary trusts the key holder with write access directly (there's no control plane to validate scopes against locally: real scope enforcement is a managed-gateway feature).

Mode is controlled by --listen / MVGC_MCP_LISTEN: omit it for stdio mode (the default, used by a locally-spawned Claude Desktop server entry), or set it to start an HTTP server for remote clients, optionally with --tls-cert/--tls-key for TLS termination. Other flags: --session-ttl (default 1h, MCP session idle timeout) and --env / MVGC_ENV (dev, stg, or prd; default dev). Run mvgc-mcp --help for the full flag and environment variable list. See the Management API's Self-Hosted Mode section for how to provision an mgk_ key locally.

Claude Desktop / Claude Code config for stdio mode:

{
  "mcpServers": {
    "axemere-local": {
      "command": "mvgc-mcp",
      "args": [
        "--gateway-url=http://localhost:7080",
        "--mgk=mgk_dev_your_key_here"
      ]
    }
  }
}

Related: Management API Reference | Key Types Reference | Approvals