Integrations API

List and run your connected systems' tools, add and change MCP servers, set their credentials and who may use them, install from the catalogue and read the audit log — from your own code over HTTP.

For developers and administrators connecting their own systems and scripts to Integrations. The OpenAPI file loads into Postman, Swagger UI or a client generator.

Updated Oct 19, 2026

Reach the systems you have connected to StudioX — and look after them — from your own code: a script, a CI job, an operations portal, a scheduler.

You want to You call
See your connected systems (your MCP servers) and what each can do GET /servers, GET /servers/{id}/tools
Read what a tool needs, and run it GET /servers/{id}/tools/{tool}, POST …/tools/{tool}/run
Add a server, change it, turn it on or off, remove it POST /servers, PATCH /servers/{id}, POST …/enable, POST …/disable, DELETE /servers/{id}
Set or rotate the credential a server uses to reach the system behind it PUT /servers/{id}/credentials/auth, PUT …/credentials/secrets/{key}
Decide who may call a server's endpoint, and issue them credentials PUT /servers/{id}/client-access, POST /servers/{id}/clients
Share a server with a colleague, or stop sharing it POST /servers/{id}/shares, DELETE …/shares/{shareId}
Install from the prebuilt catalogue GET /templates, POST /templates/{slug}/install
See what happened on your servers GET /audit

Every path below is under https://<your-host>/mcp/api/v1 — on StudioX's own service, https://www.studiox-ai.com/mcp/api/v1. The complete description, every field of every request and answer, is served by your installation at GET /mcp/api/v1/openapi.json (OpenAPI 3.1). Load it into Postman, Swagger UI or a client generator.

The API runs the same code as the Integrations screens: the same rules about who may see, run and change a server, the same checks, the same audit log. What you cannot do on the screens, you cannot do here.

There is a command line for all of this too, sxmcp — see the Integrations CLI guide.


1. Tokens

Send a credential on every call:

Authorization: Bearer <token>
Personal token mcp_pat_… Service token mcp_svc_… StudioX API key sx_live_…
Acts as You A StudioX user you create for the integration You
Made by Anyone, for themselves A business administrator You, in Studio
Made in Integrations → Settings → API access Integrations → Settings → Service tokens Studio
May do What you choose when you make it What you choose when you make it Everything your role allows
Keeps working While your StudioX sign-in is recent While the service user's key is valid While the key is valid
Business All of yours The one it was made for All of yours
Use it for Your own scripts, trying things out Systems that run on their own Scripts that already hold the key

A token is shown once, when you make it. Copy it then; it is stored only as a fingerprint and cannot be shown again. Give each token a label that says what uses it, an expiry, and only the scopes it needs.

What a token may do

Reading — your servers, their tools and schemas, the names of their credentials, the catalogue — needs no scope. Beyond that:

Scope Lets the token
run run tools
manage add, change, turn on or off and remove servers; set, rotate and remove their sign-in and secrets; install templates
admin issue and revoke client credentials, choose client access, share servers and stop sharing them; read the audit log

Tick none of them and the token may do all three. A scope only narrows a token: it never lets it do something its user may not.

Making a personal token

  1. Open Integrations → Settings.
  2. Under API access, give the token a label, choose an expiry and what it may do.
  3. Select Make token and copy it.

A personal token runs on your StudioX sign-in, which Integrations keeps for you while you hold a token. If you have not used Integrations for a while, calls answer 409 studiox_session_stale: open Integrations once in your browser and try again. For anything that runs unattended, use a service token.

Making a service token (business administrators)

  1. In Studio, create a user for the system that will call — servicenow-sync@your-company.com, say — in your business.
  2. Sign in as that user and make a StudioX API key.
  3. In Integrations → Settings → Service tokens, paste the key, label the token, choose its expiry and scopes, and select Make service token.

The token acts as that user, inside your business only, with that user's role. It keeps working while the key does, with nobody signed in. Give the service user the access it needs and no more: share the servers it should use with it, as you would with a colleague.

Revoking

Select Revoke beside the token in Settings. It stops working within a minute. Every change and every tool run made through the API is in the audit log with the token that made it, and Last used in Settings tells you whether a token is still in use.


2. How the API behaves

Errors always look like this:

{ "error": "This token is not allowed \"manage\". Make a token with that scope.",
  "code": "scope_missing", "scope": "manage" }
code Status What it means
invalid_request 400 The request is not what the endpoint takes; details says which field
unauthorized 401 No credential, or one that is unknown, revoked or expired
forbidden 403 You may not do this to this server — the message says what access you have
scope_missing 403 The token was not made for this; scope names what it needs
not_found 404 No such thing, or not one you can see
conflict 409 Refused in its current state — the message says why; reason gives the case, e.g. HELD_IN_VAULT, tool_disabled
studiox_session_stale 409 A personal token's sign-in has lapsed: open Integrations once
gone 410 A retired template: the API behind it no longer exists
rate_limited 429 Too many requests; wait Retry-After seconds
upstream_error 502 The system behind the server refused or failed; its answer is included
internal 500 Integrations failed; retry, and report it with the time if it repeats

Rate limit. 600 requests a minute per token. Running a tool counts as 5. Your administrator can change the limit for your installation.

Audit. Every call that changes something, and every tool run, is recorded with your email, the token, the path and the outcome.

Servers by id. Paths take the server's id, as GET /servers lists it.


3. Your servers and their tools

List the servers you can see, and find one:

export MCP=https://www.studiox-ai.com/mcp/api/v1
export TOKEN=mcp_pat_…

curl -s "$MCP/servers?search=jira" -H "Authorization: Bearer $TOKEN"
{ "servers": [ { "id": "6c1d…", "name": "Jira", "slug": "jira", "kind": "external", "isActive": true,
  "endpointUrl": "https://www.studiox-ai.com/mcp/serve/acme/jira", "toolCount": 40, "visibility": "owned" } ],
  "total": 1, "limit": 50, "offset": 0 }

kind is internal for a server built in Integrations, external for a remote MCP server you registered, simulator for a simulated one. endpointUrl is where assistants and other MCP clients reach it.

A server's tools, then one tool's input schema:

curl -s "$MCP/servers/$ID/tools" -H "Authorization: Bearer $TOKEN"
curl -s "$MCP/servers/$ID/tools/search_issues" -H "Authorization: Bearer $TOKEN"

Run it:

curl -s -X POST "$MCP/servers/$ID/tools/search_issues/run" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "arguments": { "jql": "project = OPS AND status = Open" } }'
{ "ok": true, "tool": "search_issues", "toolStatus": 200, "durationMs": 412, "result": { … } }

The tool runs as you, with the server's stored sign-in — or with your own connected account, on a server where each person signs in for themselves. A tool its owner has turned off is not run (409, reason tool_disabled). A tool that runs and fails answers 502 upstream_error with what the system behind it returned.

Who may run a server's tools is the same as on the server page: its owner, people it is shared with, and members of the business that owns it. A server another business has made available to yours can be mounted on an assistant, not run from here.


4. Adding and changing servers

Register a remote MCP server, then read its tools:

curl -s -X POST "$MCP/servers" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "Field Service", "isExternal": true, "serveUrl": "https://mcp.example.com/mcp",
        "authMode": "bearer", "authConfig": { "token": "…" } }'

curl -s -X POST "$MCP/servers/$ID/rediscover" -H "Authorization: Bearer $TOKEN"

Or install one from the catalogue — see section 7. A server is created in your business unless you say "scope": "personal".

Change it, turn it off and on, remove it:

curl -s -X PATCH "$MCP/servers/$ID" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "description": "Work orders and technician schedules" }'
curl -s -X POST "$MCP/servers/$ID/disable" -H "Authorization: Bearer $TOKEN"
curl -s -X POST "$MCP/servers/$ID/enable"  -H "Authorization: Bearer $TOKEN"
curl -s -X DELETE "$MCP/servers/$ID"       -H "Authorization: Bearer $TOKEN"

PATCH changes name, description, slug, isActive, serveUrl, toolTimeoutMs and shareAllowedDomain; only the server's owner may change it. Removing a server also takes it off every assistant using it. Its owner can remove it, and so can a business administrator for a business server.


5. Credentials a server uses

A server reaches the system behind it with a sign-in (bearer token, API key, basic, custom headers, OAuth client credentials, each person's own account) and, for servers built here, named secrets its tools refer to as {{KEY}}. The API never returns a stored value — only the mode and the names of what is set:

curl -s "$MCP/servers/$ID/credentials" -H "Authorization: Bearer $TOKEN"
{ "serverId": "…", "auth": { "mode": "bearer", "fieldsSet": ["token"], "heldInVault": false },
  "secrets": [ { "key": "API_KEY", "scheme": null, "createdAt": "2026-10-18T19:02:11.000Z" } ] }

Rotate the sign-in, or remove it:

curl -s -X PUT "$MCP/servers/$ID/credentials/auth" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{ "mode": "bearer", "config": { "token": "the-new-token" } }'
curl -s -X DELETE "$MCP/servers/$ID/credentials/auth" -H "Authorization: Bearer $TOKEN"

Leave a field blank to keep what is stored. A sign-in held in your vault is changed in the vault (409, reason HELD_IN_VAULT).

Create or rotate a secret, or remove it:

curl -s -X PUT "$MCP/servers/$ID/credentials/secrets/API_KEY" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{ "value": "…" }'
curl -s -X DELETE "$MCP/servers/$ID/credentials/secrets/API_KEY" -H "Authorization: Bearer $TOKEN"

The new value is stored before the old one is removed, so a rotation never leaves the server without one.


6. Who may use a server

Two different things decide this.

Who may call its endpoint (endpointUrl) — assistants, missions, other MCP clients. A server is open unless you choose otherwise. To require a credential, issue one first, then switch it on:

curl -s -X POST "$MCP/servers/$ID/clients" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{ "name": "ops-portal" }'
# → { "client": { "id": "…", "name": "ops-portal" }, "secret": "…" }   shown this once

curl -s -X PUT "$MCP/servers/$ID/client-access" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{ "mode": "bearer" }'

Callers then send Authorization: Bearer <secret> (or the header you name with "mode": "api_key", "headerName": "X-Subscription-Key", or Basic with the credential's name as the username). Assistants already using the server are given a credential of their own when you switch it on, so they keep working. List and revoke credentials with GET /servers/{id}/clients and DELETE /servers/{id}/clients/{clientId}; a revoked credential is refused from its next call.

Who may see and change it in Integrations — shares:

curl -s -X POST "$MCP/servers/$ID/shares" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{ "email": "dana@your-company.com", "permission": "read" }'
curl -s "$MCP/servers/$ID/shares" -H "Authorization: Bearer $TOKEN"
curl -s -X DELETE "$MCP/servers/$ID/shares/$SHARE_ID" -H "Authorization: Bearer $TOKEN"

read lets them see and run it; admin lets them change it too. Only the owner and people with admin access can see or change the list.


7. The catalogue

curl -s "$MCP/templates?search=servicenow" -H "Authorization: Bearer $TOKEN"
curl -s "$MCP/templates/servicenow" -H "Authorization: Bearer $TOKEN"
curl -s -X POST "$MCP/templates/servicenow/install" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{}'

A template's answer lists the secrets its API needs (secrets) — set them with section 5 after installing. Installing a template you already have answers 200 with "alreadyExisted": true, and names any tools the catalogue gained since (missingTools); send "reconcile": true to add them.


8. The audit log

curl -s "$MCP/audit?serverId=$ID&status=error&pageSize=20" -H "Authorization: Bearer $TOKEN"
curl -s "$MCP/audit?category=api" -H "Authorization: Bearer $TOKEN"

Filter by serverId, category (admin, tool_call, share, import, api), action, status and search. Business administrators see the servers of their business; everyone else sees the servers they own or that are shared with them.


9. Reference

GET    /version                                   no credential
GET    /openapi.json                              no credential
GET    /me
GET    /servers                                   ?search ?limit ?offset ?sort ?verified
POST   /servers                                   manage
GET    /servers/{id}
PATCH  /servers/{id}                              manage
DELETE /servers/{id}                              manage
POST   /servers/{id}/enable                       manage
POST   /servers/{id}/disable                      manage
POST   /servers/{id}/rediscover                   manage
GET    /servers/{id}/tools                        ?schema=1
GET    /servers/{id}/tools/{tool}
POST   /servers/{id}/tools/{tool}/run             run
GET    /servers/{id}/credentials
PUT    /servers/{id}/credentials/auth             manage
DELETE /servers/{id}/credentials/auth             manage
PUT    /servers/{id}/credentials/secrets/{key}    manage
DELETE /servers/{id}/credentials/secrets/{key}    manage
GET    /servers/{id}/clients                      admin
POST   /servers/{id}/clients                      admin
DELETE /servers/{id}/clients/{clientId}           admin
PUT    /servers/{id}/client-access                admin
GET    /servers/{id}/shares                       admin
POST   /servers/{id}/shares                       admin
DELETE /servers/{id}/shares/{shareId}             admin
GET    /templates                                 ?search ?category ?featured ?limit ?offset
GET    /templates/{slug}
POST   /templates/{slug}/install                  manage
GET    /audit                                     admin

Start with GET /me: it says who the token is, how it signed in, what it may do, and how many servers it can see.

Version history

Oct 19, 2026

First release: tokens, servers, tools, credentials, client access, sharing, the catalogue and the audit log over HTTP.

Downloads

FormatFileSizeSHA-256
Guide (PDF)mcp-api-guide.pdf457 KB5bd563a0776f0ed24f8a51527b2b3ca6d3d76dadd0a152edcf5329203d8fe360
OpenAPI 3.1 (JSON)mcp-api-openapi.json118 KB86f2ab4ce88db0d68f64008b8a94f29501cd3c651277d9456fc986df87d37474

SHA256SUMS

Check the file is ours

Compare the file's SHA-256 with the one listed for it before you run it.

# macOS / Linux
shasum -a 256 <file>

# Windows (PowerShell)
Get-FileHash <file> -Algorithm SHA256

Related

  • Missions API — Run, manage and build missions from your own code over HTTP: tokens, every endpoint, errors, jobs, worked examples.
  • Integrations CLI — List and run your connected systems' tools, add and change MCP servers, set their credentials and who may use them, install from the catalogue and read the audit log — from a terminal or a script.
  • StudioX Core API — Run your business on StudioX from your own code over HTTP: people and roles, assistants and what they know, chat, AI usage, tokens.