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
- Open Integrations → Settings.
- Under API access, give the token a label, choose an expiry and what it may do.
- 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)
- In Studio, create a user for the system that will call —
servicenow-sync@your-company.com, say — in your business. - Sign in as that user and make a StudioX API key.
- 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.