# Helpdesk MCP server

A small, complete [Model Context Protocol](https://modelcontextprotocol.io) server that lets Claude
work a support helpdesk: find a customer, read their tickets, open a new one, close one.

It is a sample of what I build to order: an MCP server for **your** API, tested, with setup steps
your team can follow. It runs with no account and no key, on built-in demo data, so you can try it
in Claude in two minutes.

## The tools

| Tool | What it does | Changes data? |
|---|---|---|
| `search_customers` | Find customers by name, email or company | no |
| `get_customer` | One customer by id | no |
| `list_tickets` | Tickets, filtered by status and/or customer | no |
| `create_ticket` | Open a ticket for a customer | yes |
| `set_ticket_status` | Move a ticket to open, pending or closed | yes |

Read tools are marked read-only, so Claude can run them without asking. Status and priority are
fixed lists in the tool schema, so Claude cannot invent a status. Errors come back as plain
sentences the model can act on ("Not found: no customer with id 'C-9'"), not stack traces.

Try asking Claude: *"Which open tickets does Northside Bakery have?"* or *"Open a high priority
ticket for Lakeview Dental: card declined on renewal."*

## Run it

Needs Python 3.10 or newer.

```
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m helpdesk_mcp
```

It talks over stdio, which is what Claude Desktop and Claude Code expect, so on its own it just
waits quietly for a client.

### Claude Desktop

Settings, Developer, Edit Config, and add (with your real path):

```json
{
  "mcpServers": {
    "helpdesk": {
      "command": "/full/path/to/mcp-sample-server/.venv/bin/python",
      "args": ["-m", "helpdesk_mcp"],
      "cwd": "/full/path/to/mcp-sample-server"
    }
  }
}
```

Restart Claude Desktop and the five tools appear under the tools menu.

### Claude Code

```
claude mcp add helpdesk -- /full/path/to/mcp-sample-server/.venv/bin/python -m helpdesk_mcp
```

## Pointing it at a real API

Set two environment variables and the demo data is replaced by HTTP calls:

```
HELPDESK_API_URL=https://your-helpdesk.example/api
HELPDESK_API_KEY=a-test-key
```

`helpdesk_mcp/backend.py` holds the whole API layer (`HttpBackend`): the routes, the bearer
token, and turning 401, 404 and 422 into readable errors. For a different API, that one class is
what changes; the tools and tests stay the same. Use a test key, never a production one.

## Tests

```
.venv/bin/python -m pytest
```

23 tests, all through a real MCP client in-process, the same calls Claude makes: the tool list and
its read-only hints, every tool's happy path and errors, input validation, and the HTTP backend
against a fake API (auth header, query parameters, JSON bodies, error mapping). No test touches the
network.

## Layout

```
helpdesk_mcp/server.py      the MCP tools
helpdesk_mcp/backend.py     demo data and the HTTP API client
helpdesk_mcp/demo_data.json four customers, four tickets
tests/test_server.py        the test suite
NOTES.md                    two setup problems on this machine, and their fixes
```

## Want one for your API?

https://www.fiverr.com/lukepapson10/build-a-custom-mcp-server-so-ai-agents-can-use-your-api

MIT licensed.