Syncro MCP Server
A Model Context Protocol (MCP) server for Syncro MSP, implementing a decision tree architecture for efficient tool navigation.
One-Click Deployment
Operator note — GitHub Packages authentication (required for one-click deploys). This server depends on the private
@wyre-technology/node-syncroSDK, which is hosted on GitHub Packages. GitHub Packages requires an authentication token on every install (no anonymous reads, even for public packages), so the cloud builders fail duringnpm installwith401 Unauthorizedunless you supply a token. Create a GitHub Personal Access Token with theread:packagesscope and provide it to the builder:
- Cloudflare Workers — set a build/environment variable named
NODE_AUTH_TOKENto your PAT.- DigitalOcean App Platform — set a build-time secret named
GITHUB_TOKENto your PAT.For local
npm install, runexport NODE_AUTH_TOKEN=$(gh auth token)first.
Features
- Decision Tree Architecture: Tools are organized by domain and loaded lazily
- Domain Navigation: Navigate between customers, tickets, assets, contacts, and invoices
- Lazy Loading: Domain handlers and the Syncro client are loaded on-demand
- Full Syncro API Coverage: Access to key Syncro MSP functionality
- Interactive Ticket Card (MCP Apps):
syncro_tickets_getrenders as an interactive card in MCP Apps hosts (Claude Desktop/web) with an in-card "Add comment" round-trip viasyncro_tickets_add_comment(internal-only by default); plain-JSON behavior is unchanged in other hosts. The card is neutral by default, brandable viawindow.__BRAND__injection orMCP_BRAND_*env vars (MCP_BRAND_NAME,MCP_BRAND_LOGO_URL,MCP_BRAND_PRIMARY_COLOR,MCP_BRAND_ACCENT_COLOR,MCP_BRAND_BG,MCP_BRAND_TEXT) — no rebuild needed.
Installation
WYRE MCP servers are distributed via OCI/GHCR images and (where available) MCPB bundles. The npm package
@wyre-ai/syncro-mcpis also published to GitHub Packages (npm.pkg.github.com); installing it requires an authenticated.npmrcwithread:packagesscope (runexport NODE_AUTH_TOKEN=$(gh auth token)locally).
Option 1: WYRE MCP Gateway (Recommended)
Use the hosted gateway at mcp.wyre.ai — paste your Syncro API key into the gateway UI and you're done.
{
"mcpServers": {
"syncro": {
"type": "http",
"url": "https://mcp.wyre.ai/v1/syncro/mcp",
"headers": {
"X-Syncro-Api-Key": "${SYNCRO_API_KEY}"
}
}
}
}
Option 2: Claude Code CLI (run from GitHub)
claude mcp add syncro \
-e SYNCRO_API_KEY=your-api-key \
-e SYNCRO_SUBDOMAIN=your-subdomain \
-- npx -y github:WYRE-AI/syncro-mcp
Option 3: Docker (GHCR)
The image listens on 0.0.0.0 inside the container and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass the service-to-service secret. In gateway mode, Syncro credentials arrive on each request as headers; they are not read from the environment.
docker run --rm \
-e CONDUIT_S2S_SECRET=your-s2s-secret \
-p 127.0.0.1:8080:8080 \
ghcr.io/wyre-ai/syncro-mcp:latest
Compose refuses to start when CONDUIT_S2S_SECRET is unset, runs AUTH_MODE=gateway with no static SYNCRO_* credentials, and publishes 127.0.0.1:8080:8080:
CONDUIT_S2S_SECRET=your-s2s-secret docker compose up
Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses SYNCRO_API_KEY:
docker run --rm \
-e CONDUIT_S2S_SECRET=your-s2s-secret \
-e AUTH_MODE=env \
-e SYNCRO_API_KEY=your-api-key \
-e SYNCRO_SUBDOMAIN=your-subdomain \
-p 127.0.0.1:8080:8080 \
ghcr.io/wyre-ai/syncro-mcp:latest
Option 4: From Source
git clone https://github.com/WYRE-AI/syncro-mcp.git
cd syncro-mcp
npm ci
npm run build
node dist/index.js
Configuration
Copy .env.example and set the variables below.
/health stays unauthenticated and does not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.
HTTP authentication
With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns 401 before vendor credentials are read. The secret is never logged.
TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
-H "X-Syncro-API-Key: $SYNCRO_API_KEY" \
-H "X-Syncro-Subdomain: $SYNCRO_SUBDOMAIN" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
In AUTH_MODE=gateway, /mcp also requires X-Syncro-API-Key (X-Syncro-Subdomain is optional). Those headers are the only credential source for that request. A request missing the API key returns 401 and does not fall back to SYNCRO_API_KEY in the process environment.
In AUTH_MODE=env, /mcp still requires a valid X-Gateway-S2S header. Vendor credentials come from SYNCRO_API_KEY and SYNCRO_SUBDOMAIN when the request does not carry X-Syncro-API-Key.
Local HTTP without a secret is development-only. It binds 127.0.0.1 and logs a warning:
MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start
Getting Your API Key
- Log in to your Syncro MSP account
- Navigate to Settings > API Tokens
- Generate a new API token with appropriate permissions
Architecture
Decision Tree Navigation
The server uses a hierarchical approach to tool discovery:
- Initial State: Only navigation and status tools are exposed
- After Navigation: Domain-specific tools become available
- Back Navigation: Return to the main menu to switch domains
This reduces cognitive load and improves LLM tool selection accuracy.
Available Domains
Tools Reference
Navigation Tools
syncro_navigate
Navigate to a domain to access its tools.
{
"domain": "customers" | "tickets" | "assets" | "contacts" | "invoices"
}
syncro_back
Return to the main menu from any domain.
syncro_status
Show current navigation state and credential status.
Customers Domain
syncro_customers_list
List customers with optional filters.
{
"query": "search term",
"business_name": "Company Inc",
"email": "[email protected]",
"include_disabled": false,
"page": 1,
"per_page": 25
}
syncro_customers_get
Get a specific customer by ID.
{
"customer_id": 123
}
syncro_customers_create
Create a new customer.
{
"business_name": "Acme Corp",
"firstname": "John",
"lastname": "Doe",
"email": "[email protected]"
}
syncro_customers_search
Search customers by query string.
{
"query": "acme",
"limit": 25
}
Tickets Domain
syncro_tickets_list
List tickets with optional filters.
{
"customer_id": 123,
"status": "Open",
"user_id": 456,
"resolved": false
}
syncro_tickets_get
Get a specific ticket by ID.
{
"ticket_id": 789
}
syncro_tickets_create
Create a new ticket.
{
"customer_id": 123,
"subject": "Network Issue",
"problem_type": "Network",
"comment_body": "Initial description"
}
syncro_tickets_update
Update an existing ticket.
{
"ticket_id": 789,
"status": "Resolved",
"user_id": 456
}
syncro_tickets_add_comment
Add a comment to a ticket.
{
"ticket_id": 789,
"body": "Comment text",
"hidden": false
}
Assets Domain
syncro_assets_list
List assets with optional filters.
{
"customer_id": 123,
"asset_type": "Desktop"
}
syncro_assets_get
Get a specific asset by ID.
{
"asset_id": 456
}
syncro_assets_search
Search assets by query or serial number.
{
"query": "workstation",
"asset_serial": "SN12345"
}
Contacts Domain
syncro_contacts_list
List contacts with optional filters.
{
"customer_id": 123,
"query": "john"
}
syncro_contacts_get
Get a specific contact by ID.
{
"contact_id": 789
}
syncro_contacts_create
Create a new contact.
{
"customer_id": 123,
"name": "Jane Smith",
"email": "[email protected]"
}
Invoices Domain
syncro_invoices_list
List invoices with optional filters.
{
"customer_id": 123,
"status": "sent",
"since_date": "2024-01-01"
}
syncro_invoices_get
Get a specific invoice by ID.
{
"invoice_id": 456
}
syncro_invoices_create
Create a new invoice.
{
"customer_id": 123,
"due_date": "2024-02-01"
}
syncro_invoices_email
Email an invoice to the customer.
{
"invoice_id": 456,
"subject": "Your Invoice"
}
Rate Limiting
Syncro API has a rate limit of 180 requests per minute. The underlying @wyre-technology/node-syncro library handles rate limiting automatically.
Development
# Install dependencies. The @wyre-technology/node-syncro SDK lives on GitHub
# Packages, so authenticate first:
export NODE_AUTH_TOKEN=$(gh auth token)
npm install
# Build
npm run build
# Run in development (stdio)
npm run dev
# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http npm start
# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 MCP_TRANSPORT=http npm start
# Type check
npm run typecheck
# Lint
npm run lint
License
Apache-2.0
