Give AI agents full access to the Sevalla PaaS API. Just 2 tools.
A remote Model Context Protocol server that exposes the entire Sevalla PaaS API through just 2 tools instead of ~200. AI agents write JavaScript that runs in sandboxed V8 isolates to discover and call any API endpoint on demand.
search - query the OpenAPI spec to discover endpoints, parameters, and schemas
execute - run JavaScript in a sandboxed V8 isolate that calls the API via sevalla.request()
This reduces context window usage by ~99% compared to traditional one-tool-per-endpoint approaches.
Cloudflare came up with the Code Mode MCP pattern: instead of registering one tool per API endpoint, you give the agent two tools. One to search the API spec, one to execute code against it. Simple idea, massive difference in practice.
As a Cloudflare partner, we took this pattern and built it for the Sevalla PaaS API. The sandbox architecture and tool design are inspired by codemode, an open-source implementation of the same pattern.
Any MCP client can now manage Sevalla infrastructure through conversation. The AI writes and runs API calls in a secure V8 sandbox. No SDK needed, no boilerplate, no 200-tool context window.
Related MCP server: Servonaut
Connect your MCP client to the hosted server at https://mcp.sevalla.com/mcp. Authentication is handled via OAuth — your client will open a browser to log in with your Sevalla account. No API keys needed in the config.
claude mcp add --transport http sevalla https://mcp.sevalla.com/mcpThen type /mcp inside Claude Code and select Authenticate to complete the OAuth flow.
Add via Settings → Connectors → Add Connector and enter https://mcp.sevalla.com/mcp as the URL. Claude Desktop handles OAuth automatically.
Add to .cursor/mcp.json in your project root:
{
"mcpServers": {
"sevalla": {
"url": "https://mcp.sevalla.com/mcp"
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"sevalla": {
"serverUrl": "https://mcp.sevalla.com/mcp"
}
}
}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.
Sevalla API keys support granular permissions — you can create a read-only key if you want your agent to query infrastructure without modifying it. Full API reference at api-docs.sevalla.com (base URL: api.sevalla.com/v3).
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 mcp remove sevallaThen 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 sevallaOpen 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.
Delete the sevalla entry from .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). Then clear cached OAuth tokens:
rm -rf ~/.mcp-authDelete the sevalla entry from ~/.codeium/windsurf/mcp_config.json.
opencode mcp logout sevallaThen delete the sevalla entry from opencode.json in your project root.
MCP Client (Claude, Cursor, etc.)
│
│ POST /mcp
│ Authorization: Bearer <sevalla-api-key>
▼
┌─────────────────────────────┐
│ Sevalla MCP Server │
│ (Hono + StreamableHTTP) │
│ │
│ ┌───────────────────────┐ │
│ │ CodeMode │ │
│ │ • search tool │ │
│ │ • execute tool │ │
│ │ • V8 sandboxed JS │ │
│ └───────────────────────┘ │
└──────────────┬──────────────┘
│ fetch() with Bearer token
▼
https://api.sevalla.com/v3Each request creates an isolated MCP session bound to the caller's API key. The server is fully stateless.
Once connected, the AI agent discovers and calls APIs on your behalf:
// Search for the right endpoint
const endpoints = await sevalla.search('list all applications')
// Execute an API call in the V8 sandbox
const apps = await sevalla.request({
method: 'GET',
path: '/applications',
})Requirements: Node.js 24+ (TypeScript runs natively, no build step)
git clone https://github.com/sevalla-hosting/mcp.git
cd mcp
pnpm install
pnpm startOr with Docker:
docker build -t sevalla-mcp .
docker run -p 3000:3000 sevalla-mcppnpm dev # Hot reload (node --watch)
pnpm test # Run tests (node:test)
pnpm check:code # tsc + oxlint + oxfmtExecute 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);
}
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | JavaScript async arrow function that uses `sevalla.request()` to make API calls |
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.
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.
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.
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.
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.
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.
Search the API specification to discover available endpoints. All $refs are pre-resolved inline.
Paths in spec.paths are ready to pass to the execute tool unchanged.
Tags: Applications, Static sites, Databases, Load balancers, Object storages, Pipelines, Webhooks, API Keys, Projects, Docker Registries, Resources, Global Environment Variables, Device Authorization, Git, Users
Endpoints: 143
Types: interface OperationInfo { summary?: string; description?: string; tags?: string[]; parameters?: Array<{ name: string; in: string; required?: boolean; schema?: unknown; description?: string }>; requestBody?: { required?: boolean; content?: Record<string, { schema?: unknown }> }; responses?: Record<string, { description?: string; content?: Record<string, { schema?: unknown }> }>; }
interface PathItem { get?: OperationInfo; post?: OperationInfo; put?: OperationInfo; patch?: OperationInfo; delete?: OperationInfo; }
declare const spec: { paths: Record<string, PathItem>; };
Your code must be an async arrow function that returns the result.
Examples:
// Find endpoints by tag async () => { const results = []; for (const [path, methods] of Object.entries(spec.paths)) { for (const [method, op] of Object.entries(methods)) { if (op.tags?.some(t => t.toLowerCase() === 'applications')) { results.push({ method: method.toUpperCase(), path, summary: op.summary }); } } } return results; }
// Get endpoint with requestBody schema (refs are resolved) async () => { const op = spec.paths['/example']?.post; return { summary: op?.summary, requestBody: op?.requestBody }; }
// Get endpoint parameters async () => { const op = spec.paths['/example']?.get; return op?.parameters; }
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | JavaScript async arrow function to search the `spec` object |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only and idempotent behavior. The description adds that $refs are pre-resolved and code must be an async arrow function returning a result. It provides the OperationInfo and PathItem types, but does not detail error handling or performance limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized, starting with purpose, then key details (paths ready, number of endpoints), types, and examples. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of searching an API spec, the description covers necessary context: the structure of spec.paths, OperationInfo type, example functions, and clarification that $refs are resolved. No output schema exists, but return values are explained via examples and types.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the single parameter with a basic description. The description greatly enhances this with examples, structure of the spec object, and the requirement for an async arrow function, making the parameter usage crystal clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search the API specification to discover available endpoints.' It distinguishes itself from the sibling tool 'execute' by providing context that paths are ready to pass unchanged to execute.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use the tool (writing async arrow functions) and provides examples. It implies the tool is for discovery before using execute, but does not explicitly mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0executesearchScored across 2 tools
The 'search' tool discovers endpoints, while the 'execute' tool makes API calls. Their purposes are completely distinct with no overlap.
Both tool names are single-word imperative verbs ('search' and 'execute'), following a consistent naming pattern.
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.
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.
Your AI Agent's Infrastructure Layer. Connect Claude, Copilot, Codex, or ChatGPT to 200+ managed open source services. Start databases, pipelines, and applications through natural language.
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
