> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect AI agents and tools to Serval using the Model Context Protocol

Serval exposes its entire public API as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) defined by the MCP specification.

## Authentication

The MCP server uses [OAuth 2.1](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). 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.

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

## Client Configuration

<Tabs>
  <Tab title="Cursor">
    Add the following to your `.cursor/mcp.json` file:

    ```json theme={null}
    {
      "mcpServers": {
        "serval": {
          "url": "https://public.api.serval.com/mcp/"
        }
      }
    }
    ```

    When you first connect, Cursor will open your browser to approve access.
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop requires a local bridge to connect to remote MCP servers. This setup uses [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which is installed automatically via `npx`.

    <Warning>
      **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:

      ```bash theme={null}
      # 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.
    </Warning>

    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):

    ```json theme={null}
    {
      "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.

    <AccordionGroup>
      <Accordion title="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 starting**

        Check the MCP logs for details. On macOS, run:

        ```bash theme={null}
        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`.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Other Clients">
    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`](https://www.npmjs.com/package/mcp-remote) to bridge the connection:

    ```bash theme={null}
    npx -y mcp-remote https://public.api.serval.com/mcp/
    ```
  </Tab>
</Tabs>

## Available Tools

Every endpoint in the [Serval public API](/api-reference/auth-api/create-token) 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 |

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

## How It Works

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

1. Your AI agent calls an MCP tool (e.g., `list_tickets`) with the required arguments
2. The server maps the tool call to the corresponding REST endpoint (`GET /v2/tickets`)
3. Path parameters, query parameters, and request bodies are constructed from the tool arguments
4. 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.

1. **Find the workflow** with `list_workflows` (or `get_workflow` if the ID is known).
2. **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.
3. **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:

1. Call the list tool without `page_token` to get the first page
2. If the response includes a `next_page_token`, pass it as `page_token` in the next call
3. 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                               |