Sevalla MCP server

A remote Model Context Protocol (MCP) server for Sevalla, so AI agents like Claude Code, Cursor and Codex can work with the applications, databases and static sites in your Sevalla company. It gives them 27 tools: 22 purpose-built tools for the everyday workflows (deploying, reading logs and metrics, environment variables, scaling, domains, creating services) and 5 generic tools that reach the rest of the Sevalla API by operation ID, split into read, create, update and delete.

Quick start

Connect your MCP client to the hosted server at https://mcp.sevalla.com/mcp, then sign in with your Sevalla account when the client opens a browser.

Claude Code

claude mcp add --transport http sevalla https://mcp.sevalla.com/mcp

Then type /mcp inside Claude Code and select Authenticate to complete the OAuth flow.

Claude Code MCP docs

Claude Desktop

Add via Settings → Connectors → Add Connector and enter https://mcp.sevalla.com/mcp as the URL. Claude Desktop handles OAuth automatically.

Claude Desktop MCP docs

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "sevalla": {
      "url": "https://mcp.sevalla.com/mcp"
    }
  }
}

Cursor MCP docs

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "sevalla": {
      "serverUrl": "https://mcp.sevalla.com/mcp"
    }
  }
}

Windsurf MCP docs

OpenCode

Add to opencode.json in your project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sevalla": {
      "type": "remote",
      "url": "https://mcp.sevalla.com/mcp"
    }
  }
}

Then run opencode mcp auth sevalla to complete the OAuth flow.

OpenCode MCP docs

Tools

Every tool carries a title and explicit readOnlyHint, destructiveHint, idempotentHint and openWorldHint annotations, so clients like Claude run read-only tools without asking and always confirm destructive ones.

The generic tools only accept operation IDs from a reviewed table generated from the Sevalla API v3 spec: the server, not the model, picks the HTTP method and path, and each tool only runs operations of its own class.

Secrets and destructive actions

Environment variable values are withheld: the tools list variable keys and their scoping, and set or delete them without ever returning a value. Everything else the Sevalla API offers is available, including deleting entire services, managing API keys and operations that issue a new secret (rolling a webhook secret, regenerating a deployment hook, rotating storage credentials), which return that secret. Destructive tools are annotated so Claude asks for confirmation before each call. Commands run inside a process (execProcessCommandV3) and application logs can still show secrets.

Authentication

Clients sign in with OAuth: the client opens a browser, you approve the connection in the Sevalla dashboard, and the approval creates an API key for it. No API key goes in the client's config. Clients without OAuth can send a Sevalla API key as Authorization: Bearer <api-key> instead.

Every tool is limited by the permissions of the Sevalla API key behind the connection. Sevalla API keys support granular permissions, so a read-only key keeps an agent read-only. Full API reference at api-docs.sevalla.com.

How it works

Each request creates a fresh MCP server bound to the caller's API key; nothing is stored between requests. The server speaks MCP 2026-07-28 (server/discover, per-request metadata, cacheable tool lists) and still serves clients on the 2025 revisions (2025-11-25 back to 2024-11-05) over the same URL, with the same tools.

Sign-in is OAuth 2.1 with PKCE. Clients identify themselves with an OAuth Client ID Metadata Document (as Claude, ChatGPT and VS Code do) or, for older clients, Dynamic Client Registration. The flow is stateless too: pending authorizations are HMAC-signed into the callback URL, authorization codes are AES-256-GCM encrypted, and access tokens are encrypted and bound to https://mcp.sevalla.com/mcp.

Examples

• "Why did the latest deployment of storefront fail?"
• "Deploy the main branch of storefront and tell me when it's live."
• "Summarize the errors in storefront's runtime logs from the last hour."
• "Create a PostgreSQL database in Frankfurt and connect it to storefront."
• "Add shop.example.com to storefront and tell me which DNS records to create."

Uninstall

To fully remove the Sevalla MCP server, delete the server configuration and clear stored OAuth credentials.

Removing the MCP server does not delete your API key on Sevalla. To revoke it, go to app.sevalla.com/api-keys.

Claude Code

claude mcp remove sevalla

Then clear the stored OAuth token: run /mcp inside Claude Code, select sevalla, and choose Clear authentication.

If the server was added at a non-default scope, specify it explicitly:

claude mcp remove --scope user sevalla
claude mcp remove --scope project sevalla

Claude Code MCP reference

Claude Desktop

Open Settings → Connectors, find the Sevalla connector, and remove it. Then fully quit and restart Claude Desktop.

OAuth tokens are stored in the operating system keychain (macOS Keychain / Windows Credential Manager). To remove them, delete the Sevalla entry from your keychain manually.

Claude Desktop MCP docs

Cursor

Delete the sevalla entry from .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). Then clear cached OAuth tokens:

rm -rf ~/.mcp-auth

Cursor MCP docs

Windsurf

Delete the sevalla entry from ~/.codeium/windsurf/mcp_config.json.

Windsurf MCP docs

OpenCode

opencode mcp logout sevalla

Then delete the sevalla entry from opencode.json in your project root.

OpenCode MCP docs

Self-hosting

Requirements: Node.js 26 (24 also works) and pnpm 12. TypeScript runs natively, no build step.

git clone https://github.com/sevalla/mcp.git
cd mcp
pnpm install
pnpm start

Or with Docker:

docker build -t sevalla-mcp .
# OAUTH_SECRET (base64url-encoded 32 bytes) comes from the environment
docker run -p 3000:3000 -e OAUTH_SECRET sevalla-mcp

Client IP in production. The device-code rate limit is applied per end-user IP, so the server must read that IP from something your edge controls. Behind Cloudflare, set CLIENT_IP_HEADER=cf-connecting-ip, and make sure the origin cannot be reached without going through Cloudflare, otherwise the header can be forged. Without Cloudflare, set TRUSTED_PROXY_HOPS to the number of proxies that append to X-Forwarded-For. The defaults read the right-most entry, which behind a CDN or load balancer is usually a proxy address, so every user would share one limit.

Development

# Hot reload (node --watch)
pnpm dev

# Unit and end-to-end tests (node:test), e2e as both 2026-07-28 and 2025 clients
pnpm test

# End-to-end tests: real HTTP server, MCP SDK client, fake Sevalla API
pnpm test:e2e

# Live checks: client metadata documents; API smoke test and fake API fidelity with SEVALLA_E2E_API_KEY
pnpm test:live

# Evals through headless Claude Code against the fake API (see evals/)
pnpm eval

# tsc + oxlint + oxfmt
pnpm check:code

# Regenerate src/sevalla/operations.json from the live API spec
pnpm sync:operations

# Fail if the live API spec drifted from the snapshot
pnpm check:operations

The policy tests in test/policy.test.ts enforce Anthropic's connector directory requirements on the live tool list: titles and explicit hints on every tool, read/write separation, descriptions that describe rather than instruct, and a size budget for the tool definitions.

License

MIT. See LICENSE.