Syncro MCP Server

An MCP server for the Syncro (SyncroMSP) REST API, the PSA + RMM platform for MSPs. It lets an AI agent read customers, contacts, tickets with their comments, assets and invoices and, on explicit request, create customers, contacts, tickets and invoices, update tickets, add ticket comments and email invoices.

• Transport: MCP Streamable HTTP at POST /mcp, health probe at GET /health

• Stateless and multi-tenant: credentials arrive on every request as HTTP headers and are never stored; every tool is listed from the first tools/list

• Python 3.12, uv, FastMCP, httpx

• License: Apache-2.0, Copyright 2026 MSPbots.ai

Authentication headers

Where to get them:

• In Syncro open Admin -> API Tokens and create a token with the permissions the agent needs: view rights on Customers, Contacts, Tickets, Assets and Invoices for the read tools; create / edit rights only for the areas it should change.

• The subdomain is the first part of the address you log in to Syncro with.

How the key is sent to Syncro: as Authorization: Bearer <token> to https://{subdomain}.syncromsp.com/api/v1/..., never as a query parameter, so it does not appear in URLs or access logs. Values that look like unresolved templates (${...}) are treated as missing.

A request to /mcp without both headers gets HTTP 401 listing them; a subdomain that is not a plain account name gets HTTP 400.

Related MCP server: SyncroMSP MCP Server

Tools

All tools return a JSON string. Syncro returns list results in pages of 25 with {total_entries, total_pages, page}; pass page for more and per_page (at most 25) to return fewer. A few filters the Syncro API does not offer are applied by this server over up to 5 pages; those results report scanned_pages and next_page instead of totals.

* applied by this server, as described above.

Errors come back as a JSON envelope instead of an exception:

{"error": {"code": "unauthorized", "message": "Syncro returned HTTP 401 for me: the API key was rejected ...", "retryable": false}}

code is one of not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error. Syncro allows 180 requests per minute per source IP address, so every account served from the same egress IP shares that budget; reads are retried with backoff on 429 (honouring Retry-After), 5xx and network errors, writes only on 429.

Run locally

uv sync
uv run python -m syncro_mcp          # listens on 0.0.0.0:8080

or with Docker:

docker build --platform linux/amd64 -t syncro-mcp:dev .
docker run --rm -p 8080:8080 syncro-mcp:dev

Configuration (environment variables, all optional): MCP_HTTP_HOST (default 0.0.0.0), MCP_HTTP_PORT (default 8080), LOG_LEVEL (default INFO). Credentials are never read from the environment.

Testing example

# list tools
curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Syncro-Subdomain: acme" \
  -H "X-Syncro-API-Key: your-syncro-api-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# open tickets of one customer
curl -s http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Syncro-Subdomain: acme" \
  -H "X-Syncro-API-Key: your-syncro-api-key" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"syncro_tickets_list","arguments":{"customer_id":123,"resolved":false}}}'

Unit tests (no network access needed):

uv run pytest

Delivery notes

• Built on the published API reference. Every call follows Syncro's OpenAPI document (api-docs.syncromsp.com). Where the older version sent filters that endpoint does not have, they are now mapped to the documented ones (since -> since_updated_at, invoice paid / unpaid) or applied by this server and flagged with scanned_pages.

• Tool count (21). Tool names and required parameters are unchanged.

• Invoice states. Syncro exposes paid / unpaid amounts, not draft / sent / viewed / void states; those values now return a clear invalid_argument instead of being ignored.

• Removed no-op parameters. syncro_invoices_email no longer takes cc_emails, subject or message: the endpoint has no such options (it uses the account's invoice email settings). per_page is capped at Syncro's fixed page size of 25.

• Write tools. The 7 tools marked write change records or contact the customer; their descriptions tell the agent to use them only on explicit request. There are no delete tools.

• No interactive prompts. Older versions asked the user for a date range before an unfiltered ticket list, which a stateless gateway cannot relay; lists now page instead.

License

Apache License 2.0 - see LICENSE and NOTICE.