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. The tools most commonly used by employees connecting through an AI assistant: Tickets

Tool	Use case
`create_ticket`	”I need to submit a ticket”
`get_ticket` · `search_tickets`	”What’s the status of my ticket?”
`list_ticket_messages` · `create_ticket_message`	”What did the agent say?” / “Let me add more details”
`update_ticket`	”I want to close this” / “This is actually urgent”
`list_statuses` · `list_priorities` · `list_labels`	Pick valid values when creating or updating

Access requests

Tool	Use case
`list_requestable_roles` · `create_access_request` · `list_access_requests`	”I need access to X” / “Did my access request get approved?”

Workflows

Tool	Use case
`list_workflows`	”What automations can I kick off?”
`start_workflow_run` · `await_workflow_run_result`	”Run the onboarding workflow for me”
`search_workflow_runs` · `get_workflow_run` · `list_workflow_run_tasks`	”What’s the status of that provisioning request I triggered?”

Identity

Tool	Use case
`get_current_user`	Know who the employee is before acting

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",
        ...
      }
    ]
  }

Running Workflows

AI agents can run Serval workflows directly through MCP. Workflow runs are asynchronous: starting a run returns immediately, and the agent waits for (or polls) the result.

Find the workflow with list_workflows (or get_workflow if the ID is known).
Start the run with start_workflow_run, passing the workflow_id and any workflow arguments in arguments as a JSON object encoded into a string — not a raw JSON object (see the example below). The run starts on the workflow’s currently-published version; pass workflow_version_id to pin a specific version. The response returns the run immediately with a pending or running status.
Wait for the result with await_workflow_run_result, which blocks until the run reaches a terminal status or wait_timeout_seconds elapses (default 30s, capped at 60s). If the response has timed_out: true, call it again to keep waiting — or use get_workflow_run to poll.

Agent: "Request a new laptop for me"

→ Calls MCP tool: list_workflows
← Finds: "Laptop Request" (id: wf-456)

→ Calls MCP tool: start_workflow_run
  Arguments: { "workflow_id": "wf-456", "arguments": "{\"model\": \"MacBook Pro 14\"}" }
← Returns: { "data": { "id": "run-789", "status": "PENDING", ... } }

→ Calls MCP tool: await_workflow_run_result
  Arguments: { "id": "run-789" }
← Returns: { "data": { "id": "run-789", "status": "COMPLETED", ... }, "timed_out": false }

Runs execute under your identity and permissions, exactly as if you started the workflow in Serval. Starting a run requires the run_published_workflow permission (team contributor role or above), so users without it won’t see the workflow-run tools in their tool list. Running an unpublished draft version instead requires create_workflow_run (team builder role or higher). Workflows with approval requirements still go through their normal approval process. The run stays in progress until approvers act, so long-running runs are expected.

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

​Running Workflows

​Pagination

​Error Handling

Base URL

Authentication

Client Configuration

Available Tools

How It Works

Example Usage

Running Workflows

Pagination

Error Handling