Splynx MCP Server

MCP (Model Context Protocol) is an open standard that lets AI assistants talk to external systems in a safe, structured way. With the Splynx MCP server, your Splynx instance becomes one of those systems: an AI client connects to it and can work with the full Splynx admin API (~500 operations) on your behalf - always within the permissions of the account or API key it connects with.

What you can ask it to do

You describe the goal in plain language; the assistant finds the right operation, calls Splynx, and reports back. Everything it does is logged - see Audit trail.

You can connect either with your administrator account (OAuth) or with an API key. Choose one.

2a · Sign in with your Splynx account (OAuth - recommended)

Nothing to prepare in Splynx. The AI client opens your browser, you log into Splynx, approve the connection, and you’re done. The assistant then acts with your administrator permissions.

The Splynx server advertises the standard OAuth 2.1 discovery endpoints, so compatible clients configure themselves automatically. See Client configuration for per‑client steps.

2b · Create an API key (Basic Auth)

Use this for automation or clients that prefer a static credential.

2c · Permissions decide what the assistant can do

The MCP server adds no new permission system - it reuses Splynx’s existing permissions exactly. Whatever you can do in Splynx defines what the assistant can do; nothing more.

• API key (Basic Auth): the key’s permission tree applies (Administration → API keys). Each API operation maps to a permission; only the permitted ones are available.
• OAuth (account sign‑in): the signed‑in administrator’s role and permissions apply - the same access that admin has in the web interface.

Permissions are granted per module and per action (e.g. view vs add vs delete), so you control access precisely - for example: read customers, create tickets, but no access to finance at all.

How this shapes the assistant in practice:

• Hidden, not just blocked. Operations you don’t have permission for don’t even appear when the assistant searches for tools - so it won’t try to use them. If it does call something out of scope, Splynx returns Access denied.
• Read‑only stays read‑only. A key or role with only view permissions produces an assistant that can look things up but never change anything. Grant add / update / delete only if you want it to create or modify data.
• Scope per connection. Different keys (or admins) connected from different clients each get their own access - a narrow reporting key and a full‑access admin can both connect, each limited to its own permissions.

Replace https://your-splynx.example.com with your real Splynx URL everywhere below.

The selected method applies to all three clients below.

# Prints the value to put after "Basic "
printf '%s' 'YOUR_KEY:YOUR_SECRET' | base64

Claude Code

claude mcp add --transport http splynx https://your-splynx.example.com/mcp

{
  "mcpServers": {
    "splynx": {
      "type": "http",
      "url": "https://your-splynx.example.com/mcp"
    }
  }
}

claude mcp add --transport http splynx https://your-splynx.example.com/mcp \
  --header "Authorization: Basic BASE64_OF_KEY_COLON_SECRET"

{
  "mcpServers": {
    "splynx": {
      "type": "http",
      "url": "https://your-splynx.example.com/mcp",
      "headers": {
        "Authorization": "Basic BASE64_OF_KEY_COLON_SECRET"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per‑project).

{
  "mcpServers": {
    "splynx": {
      "url": "https://your-splynx.example.com/mcp",
      "headers": {
        "Authorization": "Basic BASE64_OF_KEY_COLON_SECRET"
      }
    }
  }
}

{
  "mcpServers": {
    "splynx": {
      "url": "https://your-splynx.example.com/mcp"
    }
  }
}

Claude Desktop

Claude Desktop’s config file is at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "splynx": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-splynx.example.com/mcp"]
    }
  }
}

{
  "mcpServers": {
    "splynx": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-splynx.example.com/mcp",
        "--header", "Authorization: Basic BASE64_OF_KEY_COLON_SECRET"
      ]
    }
  }
}

Restart Claude Desktop after editing the config file.

Once the server is connected, the assistant gains access to the Splynx tools automatically - you don’t call tools by hand. Just describe what you want in plain language in your normal chat with the assistant, and it works out which operation to run.

You can write in any language - the assistant translates your request into an English search behind the scenes. The first time you ask for something it may take a moment, as it searches for the right operation, reads its schema, then runs it.

Example requests

Getting good results

• Be specific. Give a name, ID, customer login, or date range - “customer #42” beats “that customer”. The more precise the request, the more precise the call.
• Ask it to preview changes. For anything that writes data, say “show me what you’ll change first” and confirm before it proceeds. Operations marked destructive should always be confirmed.
• Steer it to a category when a term is ambiguous: “in finance, find…” or “search support tickets for…”.
• Refine if results look short. Ask it to “show more” or to add a filter - results are paginated.
• It only sees what you can do. If it can’t find or perform something, the connected account or API key probably lacks that permission (see Troubleshooting).

Splynx exposes ~500 admin API operations. Listing them all would overwhelm an AI client, so the server presents just 3 meta‑tools and lets the assistant discover the rest on demand. You don’t need to know the API - describe the goal and the assistant does the lookup.

Behind the scenes the assistant simply does search → inspect → run. For example, “block customer internet” → finds update_customer → reads its schema → calls it with { id: 42, status: "blocked" }.

Operations are grouped into categories you (or the assistant) can target with the optional category parameter:

Tool safety hints

Each operation is annotated so a well‑behaved assistant treats it correctly:

Every operation an AI client performs is written to the Splynx API request log and flagged as AI‑initiated (logs_api.is_ai = '1'). This lets you review exactly what an assistant did, when, and on whose behalf.

• MCP traffic is always logged, even if general API logging is turned off - AI activity is audited unconditionally.
• For OAuth connections the log attributes the request to the administrator who signed in; for API‑key connections, to the API key.
• In the admin panel, open the API request log under Administration → Logs; AI‑initiated requests carry the AI marker so you can identify and filter them.

Connecting an AI assistant doesn’t widen your attack surface or expose data beyond what an administrator already sees - provided you connect with appropriate permissions.

• Admin‑only, permission‑bound. This is the administrator API. The assistant can only reach data and actions the connected account or API key is permitted to use (see 2c); it is not a customer‑facing channel.
• What the AI provider sees. Splynx returns data to your MCP client. What the client then sends to its AI model is governed by that client and your conversation - like any other tool the assistant uses. Treat whatever you ask about (customer names, invoices, etc.) as data that may be processed by the AI provider. Review your client/provider’s data‑handling terms, and don’t pull more personal data into a conversation than the task needs.
• Least privilege. Connect with a dedicated, narrowly‑scoped API key (or an admin whose role is already limited) so the assistant can only touch what it needs. A read‑only key can’t change or delete anything.
• Encrypted transport. All traffic is over HTTPS; OAuth additionally requires HTTPS and validated redirect URIs.
• No new stored secrets in Splynx. OAuth issues short‑lived tokens; API keys are the ones you already manage. Credentials live in the client config, so protect that file - especially for API‑key setups, where it contains the secret.
• Everything is audited. All AI activity is logged and flagged (see Audit trail).
• IP and origin controls. API‑key IP allow‑lists and the Allowed‑origins setting both apply to MCP.