Helpdesk MCP server

A small, complete Model Context Protocol 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

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."

Related MCP server: Freshservice MCP Server

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

{
  "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.