Skip to main content
Glama
Sign In
Sevalla MCP server

Sevalla MCP server

by sevalla
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Sevalla MCP server

Deploy, debug and manage Sevalla applications, databases and static sites from any AI agent.

CI License: MIT Node.js

Docs · Sevalla · mcp.sevalla.com

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

Related MCP server: Emisar

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.

Area

Tools

Discovery

list_services, get_application, get_static_site, get_database, get_platform_options, search_sevalla_docs

Deployments

list_deployments, get_deployment, get_deployment_logs, trigger_deployment, rollback_deployment

Observability

search_runtime_logs, search_access_logs, get_metrics

Configuration

list_environment_variables, set_environment_variables, delete_environment_variables, scale_process, add_domain

Create

create_application, create_static_site, create_database

Rest of the API

sevalla_api_search, sevalla_api_read, sevalla_api_create, sevalla_api_update, sevalla_api_delete

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

Variable

Purpose

PORT

HTTP port (default 3000)

OAUTH_SECRET

base64url-encoded 32 bytes; required when NODE_ENV=production

PUBLIC_URL

Public base URL used in OAuth metadata (default https://mcp.sevalla.com)

SEVALLA_FRONTEND_URL

Sevalla dashboard URL for the OAuth consent page (default https://app.sevalla.com)

SEVALLA_API_URL

Sevalla API base URL (default https://api.sevalla.com)

SEVALLA_DOCS_URL

Documentation site searched by search_sevalla_docs (default https://docs.sevalla.com)

DEVICE_CODE_TRUSTED_CLIENT_TOKEN

Service token that lets the API rate-limit OAuth sign-ins per end-user IP instead of per server IP

CLIENT_IP_HEADER

Header carrying the end-user IP, set by your edge (default x-forwarded-for; use cf-connecting-ip behind Cloudflare)

TRUSTED_PROXY_HOPS

With x-forwarded-for: number of trusted proxies that append to it; the client IP is read that many entries from the right (default 1)

SEVALLA_API_KEY

--stdio mode: the Sevalla API key

SHUTDOWN_TIMEOUT_MS

Graceful shutdown deadline (default 30000)

OPENAI_APPS_CHALLENGE

Domain verification token served at /.well-known/openai-apps-challenge for the OpenAI plugin submission

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.

Available Tools

2 tools
executeExecute Sevalla API CallA
Destructive
Inspect

Execute API calls by writing JavaScript code. First use the 'search' tool to find the right endpoints.

Use the exact path returned by the search tool. Do not pass a full URL or add an extra API version prefix.

Available in your code:

interface RequestOptions { method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; path: string; query?: Record<string, string | number | boolean>; body?: unknown; headers?: Record<string, string>; }

interface Response<T = unknown> { status: number; headers: Record<string, string>; body: T; }

declare const sevalla: { request<T = unknown>(options: RequestOptions): Promise<Response>; }; Your code must be an async arrow function that returns the result.

Examples:

// List resources async () => { const res = await sevalla.request({ method: "GET", path: "/items" }); return res.body; }

// Create a resource async () => { const res = await sevalla.request({ method: "POST", path: "/items", body: { name: "Widget" } }); return { status: res.status, body: res.body }; }

// Chain multiple calls async () => { const list = await sevalla.request({ method: "GET", path: "/items" }); const details = await Promise.all( list.body.map(item => sevalla.request({ method: "GET", path: /items/${item.id} }) ) ); return details.map(d => d.body); }

NameRequiredDescriptionDefault
codeYesJavaScript async arrow function that uses `sevalla.request()` to make API calls

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true. The description adds context by showing that the tool can make GET, POST, etc., and requires an async arrow function. It does not detail error handling or side effects, but the examples cover typical usage. Overall, it's sufficiently transparent for a execution tool with given annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy but well-structured: brief intro, key rules, interface definition, boilerplate, and examples. It is front-loaded and every section adds value. Some minor redundancy (e.g., repeating the async arrow function pattern), but overall efficient given the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (executing arbitrary JavaScript for API calls), the description covers all essential aspects: prerequisite search, code structure, available methods, request/response types, and multiple examples. No output schema exists, but the response interface is shown. The description is complete enough for an AI agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description greatly expands on the 'code' parameter by specifying it must be an async arrow function, must use sevalla.request(), must return a result, and provides the exact interface and pattern. This adds substantial meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes API calls via JavaScript code, and it explicitly differentiates from the sibling 'search' tool by instructing users to first use search to find endpoints. The verb 'execute' and resource 'Sevalla API Call' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidelines: use 'search' first, use exact path from search, avoid full URLs or extra version prefixes. It also gives code structure requirements and multiple examples, making it clear when and how to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedexecute
    • First observedsearch
Deploy Server
Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A4.6/5.0

Scored across 2 tools

Disambiguation5/5

The 'search' tool discovers endpoints, while the 'execute' tool makes API calls. Their purposes are completely distinct with no overlap.

Naming Consistency5/5

Both tool names are single-word imperative verbs ('search' and 'execute'), following a consistent naming pattern.

Tool Count3/5

With only 2 tools, the set is minimal but functional for a general-purpose API client. It is at the lower bound of what is reasonable for its broad scope.

Completeness4/5

The tools cover the full workflow of discovering and invoking API endpoints. Minor gaps may exist in area like authentication, but the core functionality is complete.

Maintenance

ActivityNo data
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers