Skills and MCP servers
Import a skill into a workspace, register an MCP server with its token, and give both to an agent.
A workspace has a library: the skills and the MCP servers its agents can use. You add an item to the library once, then give it to one or more agents of that workspace by name.
- A skill is a folder of instructions and scripts with a
SKILL.mdfile. The agent reads it when a task needs it. - An MCP server is a tool server of yours (or of your customer) that the agent calls over HTTP.
All paths below are relative to https://sokko.ai/api/v1.
Import a skill
POST /workspaces/{workspaceId}/skillsThe body is the skill folder as a list of files, each one base64-encoded.
| Field | Type | Rules |
|---|---|---|
name | string | Required. 1 to 120 characters, with at least two letters or digits. |
version | string | Optional. 1 to 80 characters. Your own label, for example 1.2.0. |
files | array | Required. 1 to 200 files, 5 MB together after decoding. One file must have the path SKILL.md. |
files[].path | string | The path inside the skill folder, up to 500 characters, with no .. segment. |
files[].contentBase64 | string | The file's bytes in standard base64. |
Files are text, script and document formats only: md, txt, json, yaml,
yml, toml, csv, xml, html, css, svg, sh, py, js, ts,
rb, go, sql and similar. A file with no extension, or a binary file, is
refused.
curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/skills \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Returns policy",
"version": "1.0.0",
"files": [
{ "path": "SKILL.md", "contentBase64": "LS0tCm5hbWU6IHJldHVybnMtcG9saWN5CmRlc2NyaXB0aW9uOiBIb3cgdG8gaGFuZGxlIGEgcmV0dXJuIHJlcXVlc3QuCi0tLQoKQSBjdXN0b21lciBjYW4gcmV0dXJuIGFuIG9yZGVyIHdpdGhpbiAxNCBkYXlzLgo=" },
{ "path": "scripts/refund.py", "contentBase64": "cHJpbnQoInJlZnVuZCIpCg==" }
]
}'The answer is 202 with the skill:
{
"id": "e2a4c6f8-1b3d-4e5f-8a7b-9c0d1e2f3a4b",
"name": "returns-policy",
"description": "How to handle a return request.",
"version": "1.0.0",
"status": "pending",
"createdAt": "2026-11-20T09:30:12.004Z",
"updatedAt": "2026-11-20T09:30:12.004Z"
}name in the answer is the skill's slug: your name in lowercase, with every
run of other characters as one dash, cut at 64 characters. Returns policy
becomes returns-policy. This slug is the name you give to an agent.
Importing a name that exists replaces the files of that skill.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | No SKILL.md, a file type that is not allowed, a bad path, or over a limit. |
| 404 | not_found | No such workspace in your account. |
| 409 | conflict | A skill of this name that an agent proposed waits for review. |
| 503 | unavailable | File storage is not available. Try again later. |
Skill statuses
| Status | Meaning |
|---|---|
pending | The files are being written to the workspace. No agent can use the skill yet. |
active | The skill is ready. You can give it to an agent. |
failed | The import did not finish. Import the skill again. |
disabled | The skill takes no new agent. Agents that have it keep it. |
An import is pending first. Read the skill until it is active before you
name it in an agent: a skill that is not active answers 409
skill_not_active there.
List, read and delete skills
GET /workspaces/{workspaceId}/skills
GET /workspaces/{workspaceId}/skills/{skillId}
DELETE /workspaces/{workspaceId}/skills/{skillId}The list comes newest first and takes limit and cursor.
curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/skills/e2a4c6f8-1b3d-4e5f-8a7b-9c0d1e2f3a4b \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY"{
"id": "e2a4c6f8-1b3d-4e5f-8a7b-9c0d1e2f3a4b",
"name": "returns-policy",
"description": "How to handle a return request.",
"version": "1.0.0",
"status": "active",
"createdAt": "2026-11-20T09:30:12.004Z",
"updatedAt": "2026-11-20T09:30:41.520Z"
}A delete answers:
{ "id": "e2a4c6f8-1b3d-4e5f-8a7b-9c0d1e2f3a4b", "deleted": true }A delete first takes the skill off every agent that has it. An agent that is
ready or failed then starts again without it.
Errors: 404 not_found.
Register an MCP server
POST /workspaces/{workspaceId}/mcp-servers| Field | Type | Rules |
|---|---|---|
name | string | Required. Lowercase letters, digits and dashes, starting with a letter or digit, up to 64. Not sokko. |
url | string | Required. An http or https URL, up to 2,048 characters, on port 443 or 80. |
auth | object | Optional. One of the three shapes below. Without it the server takes no authentication. |
description | string | Optional. Up to 2,000 characters. What the server is for. |
transport | string | Optional. Only http. |
The URL must be reachable from the public internet. It carries no user name or
password and no #fragment: a credential goes in auth.
Authentication of the server
auth | What the agent sends with each call |
|---|---|
{ "kind": "none" } | Nothing. |
{ "kind": "bearer", "token": "..." } | Authorization: Bearer <token> |
{ "kind": "header", "headerName": "X-Api-Key", "token": "..." } | <headerName>: <token> |
token: 1 to 8,192 characters, one line, no control character.headerName: letters, digits and dashes, up to 64 characters.- The token is write-only. No call returns it. Keep your own copy.
curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/mcp-servers \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "orders",
"url": "https://mcp.acme.example/customers/cust_1042/mcp",
"auth": { "kind": "bearer", "token": "mcp_live_9f8e7d6c5b4a" },
"description": "Read and change the orders of this bakery."
}'The answer is 201 with the server:
{
"id": "a7c1e3f5-2b4d-4f6a-9c8e-0d1f2a3b4c5d",
"name": "orders",
"url": "https://mcp.acme.example/customers/cust_1042/mcp",
"auth": { "kind": "bearer" },
"description": "Read and change the orders of this bakery.",
"status": "active",
"createdAt": "2026-11-20T09:33:05.310Z",
"updatedAt": "2026-11-20T09:33:05.310Z"
}For header auth, auth in the answer also carries headerName.
status is active, failed (the token could not be stored: register the
server again with the same name) or deleting.
Use one token per customer where you can. Then a token that leaks opens one customer's data, and you can rotate it without touching the others.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A bad name, header name or token, a URL that is empty or too long, or auth without its token. |
| 400 | mcp_server_url_not_allowed | The URL is refused: it is not a full http or https URL, it names a port other than 443 or 80, or it carries a user name, a password or a #fragment. |
| 400 | not_supported | transport: "stdio", or OAuth authentication. The API offers neither. |
| 404 | not_found | No such workspace in your account. |
| 409 | conflict | A server with this name exists, or is being deleted. |
List, update and delete MCP servers
GET /workspaces/{workspaceId}/mcp-servers
PATCH /workspaces/{workspaceId}/mcp-servers/{serverId}
DELETE /workspaces/{workspaceId}/mcp-servers/{serverId}The list comes newest first and takes limit and cursor. There is no call
that reads one server: find it in the list.
PATCH takes at least one of url, auth and description. An auth object
replaces the stored authentication, token included.
curl -X PATCH https://sokko.ai/api/v1/workspaces/$WORKSPACE/mcp-servers/a7c1e3f5-2b4d-4f6a-9c8e-0d1f2a3b4c5d \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://mcp.acme.example/v2/customers/cust_1042/mcp" }'The answer is the server object. A new URL or a new kind of authentication is written to every agent that has the server, and those agents start again.
An end_users agent reaches a server
with a token through the platform only, and that needs an https URL. If your
change gives the server a shape such an agent cannot use, the server is taken
off that agent, and the answer names the agents that lost it:
{
"id": "a7c1e3f5-2b4d-4f6a-9c8e-0d1f2a3b4c5d",
"name": "orders",
"url": "http://mcp.acme.example/customers/cust_1042/mcp",
"auth": { "kind": "bearer" },
"description": "Read and change the orders of this bakery.",
"status": "active",
"createdAt": "2026-11-20T09:33:05.310Z",
"updatedAt": "2026-11-21T14:02:44.120Z",
"removedFromAgents": ["3b9d7e0a-51c2-4f6d-8e1a-9c4b2d7f6a05"]
}removedFromAgents is absent when no agent lost the server.
A delete answers:
{ "id": "a7c1e3f5-2b4d-4f6a-9c8e-0d1f2a3b4c5d", "deleted": true }A delete is never refused because the server is in use. It takes the server
off every agent that has it (a ready or failed agent starts again), then
removes the token and the server.
Errors: 400 invalid_request, 400 mcp_server_url_not_allowed (a new url
that is refused, as at the create), 400 not_supported, 404 not_found, 409
conflict (the server is being deleted).
Rotate a token
POST /workspaces/{workspaceId}/mcp-servers/{serverId}/rotate-tokencurl https://sokko.ai/api/v1/workspaces/$WORKSPACE/mcp-servers/a7c1e3f5-2b4d-4f6a-9c8e-0d1f2a3b4c5d/rotate-token \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{ "token": "mcp_live_1a2b3c4d5e6f" }'The answer is the server object. The new token replaces the old one. The kind of authentication and the header name stay.
You do not redeploy anything. The new token is in use within about a minute.
An operator agent that has the server restarts briefly to load it. An
end_users agent does not hold the token, so it does not restart.
To rotate with no failed call, make your MCP server accept both tokens, rotate here, wait a few minutes, then retire the old token.
Errors: 400 invalid_request (a bad token, or a server with none
authentication), 404 not_found, 409 conflict (the server is being
deleted).
Give a skill or a server to an agent
An item in the library does nothing until an agent has it. Name it when you create the agent, or change the lists later:
curl -X PATCH https://sokko.ai/api/v1/workspaces/$WORKSPACE/agents/$AGENT \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{ "skills": ["returns-policy"], "mcpServers": ["orders"] }'- Use the skill's slug and the server's
name. - Each list replaces the agent's current list.
- A skill must be
active: otherwise 409skill_not_active. Adisabledskill stays on an agent that already has it. - A server must exist in the workspace and be
active: otherwise 400invalid_request. - A server that an
end_usersagent cannot use answers 409mcp_server_not_allowed_for_end_users. See below. - The agent can start again to load the new lists. Wait for
ready.
MCP servers of an agent for end users
An agent with audience: "end_users"
never holds the token of an MCP server:
- A server with a
bearerorheadertoken is reached through the platform. The agent calls the platform, and the platform adds the token and passes the call on to your server. The token is not on the agent's machine. Your server sees the call come from the platform's address, not from the agent's. - This needs an
httpsURL. A token server on anhttpURL is refused for such an agent with 409mcp_server_not_allowed_for_end_users, when you create the agent with it or add it in an update. Move the server tohttps, then send the request again. - A server with
"kind": "none"is reached directly.
An operator agent holds the token and calls your server directly.
See Agents.