MCP Server - Serval Documentation

Serval exposes its entire public API as an MCP (Model Context Protocol) server, allowing AI agents and LLM-powered tools to interact with your Serval workspace programmatically. Every public API endpoint is automatically available as an MCP tool.

Base URL

The MCP server is available at:

https://public.api.serval.com/mcp/

The server implements the Streamable HTTP transport defined by the MCP specification.

Authentication

The MCP server uses OAuth 2.1. Your MCP client handles authentication automatically — you provide the server URL, the client discovers OAuth endpoints, opens your browser for approval, and manages tokens. No credentials to copy or rotate.

Configure your MCP client with the server URL: https://public.api.serval.com/mcp/
When the client connects, it will open your browser to approve access to your Serval workspace.
After approval, the client receives tokens and refreshes them automatically.

Client Configuration

Cursor
Claude Desktop
Other Clients

Add the following to your .cursor/mcp.json file:

{
  "mcpServers": {
    "serval": {
      "url": "https://public.api.serval.com/mcp/"
    }
  }
}

When you first connect, Cursor will open your browser to approve access.

Claude Desktop requires a local bridge to connect to remote MCP servers. This setup uses mcp-remote, which is installed automatically via npx.

Node.js v18+ is required. Claude Desktop uses npx to run the bridge, which requires Node.js to be installed on your machine. If you don’t have it, install it before proceeding:

# macOS (Homebrew)
brew install node

# Windows
winget install OpenJS.NodeJS

# Or download from https://nodejs.org/

To verify Node.js is installed, run which node && which npx in your terminal — both should return a path.

Add the following to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "serval": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://public.api.serval.com/mcp/"]
    }
  }
}

When you first connect, mcp-remote will open your browser to approve access. Tokens are cached locally and refreshed automatically.

Troubleshooting

“Failed to spawn process: No such file or directory”Claude Desktop cannot find npx or node. This usually means Node.js is not installed, or it was installed via a version manager (nvm, fnm, volta) that is not visible to Claude Desktop. Install Node.js globally using one of the methods above, then restart Claude Desktop.“Server disconnected” immediately after startingCheck the MCP logs for details. On macOS, run:

tail -n 50 ~/Library/Logs/Claude/mcp-server-serval.log

Common causes include an expired token or a network issue reaching public.api.serval.com.

Set the server URL to https://public.api.serval.com/mcp/. The client will discover OAuth endpoints automatically and handle the browser-based approval flow.For stdio-only clients, use mcp-remote to bridge the connection:

npx -y mcp-remote https://public.api.serval.com/mcp/

Available Tools

Every endpoint in the Serval public API is available as an MCP tool. Tool names, descriptions, and input schemas are derived directly from the API specification. Tools follow a consistent snake_case naming convention matching the API operation name. For example:

Tool Name	Description
`list_tickets`	List all tickets
`create_ticket`	Create a new ticket
`get_user`	Get a specific user by ID
`list_workflows`	List all workflows
`create_access_policy`	Create a new access policy
`list_audit_log_events`	List audit log events

Use the MCP tools/list method to discover all available tools and their input schemas at runtime. Your MCP client handles this automatically.

How It Works

The MCP server translates each tool call into a REST API request:

Your AI agent calls an MCP tool (e.g., list_tickets) with the required arguments
The server maps the tool call to the corresponding REST endpoint (GET /v2/tickets)
Path parameters, query parameters, and request bodies are constructed from the tool arguments
The response is returned as the tool result

The MCP server has the same capabilities, permissions, and rate limits as the REST API. Any action you can perform through the API, your AI agent can perform through MCP.

Example Usage

Here is an example of an AI agent using the Serval MCP server to list open tickets:

Agent: "Show me all open tickets"

→ Calls MCP tool: list_tickets
  Arguments: {}

← Returns:
  {
    "data": [
      {
        "id": "abc-123",
        "title": "Cannot access VPN",
        "status": "OPEN",
        ...
      }
    ]
  }

Pagination

List endpoints return paginated results. Use the page_token parameter to retrieve subsequent pages:

Call the list tool without page_token to get the first page
If the response includes a next_page_token, pass it as page_token in the next call
Repeat until no next_page_token is returned

Error Handling

Tool calls that result in API errors return an error message with the HTTP status code and response body. Common errors include:

Status Code	Meaning
401	Invalid or expired access token
403	Insufficient permissions for the requested action
404	Resource not found
429	Rate limit exceeded

​Base URL

​Authentication

​Client Configuration

​Available Tools

​How It Works

​Example Usage

​Pagination

​Error Handling

Base URL

Authentication

Client Configuration

Available Tools

How It Works

Example Usage

Pagination

Error Handling