MCP skills API
Manage skill-embedded MCP servers that provide additional tools to agents. Each skill can bundle its own MCP server with a set of tools. Activate a skill’s MCP server on demand and deactivate it when no longer needed.
All MCP skill endpoints require session-based authentication through NextAuth. Idle MCP servers are automatically cleaned up.
Activate a skill MCP
Starts the MCP server bundled with the specified skill. Returns the server metadata including its name, version, available tools, and activation timestamp.
Path parameters
| Parameter | Type | Required | Description |
|---|
skillId | string | Yes | Identifier of the skill whose MCP server to activate |
Built-in skills
The following skills ship with built-in MCP servers:
| Skill ID | Description |
|---|
websearch | Web search tool server |
context7 | Context retrieval and semantic search |
grep_app | Code search using grep patterns |
Response
{
"success": true,
"skillId": "websearch",
"mcp": {
"name": "websearch-mcp",
"version": "1.0.0",
"tools": ["web_search", "web_fetch"],
"startedAt": "2026-04-04T12:00:00.000Z"
}
}
| Field | Type | Description |
|---|
success | boolean | Whether activation succeeded |
skillId | string | The skill that was activated |
mcp.name | string | MCP server name from the skill configuration |
mcp.version | string | MCP server version |
mcp.tools | string[] | List of tool names provided by this MCP server |
mcp.startedAt | string | ISO 8601 timestamp of when the server was started |
Errors
| Code | Description |
|---|
| 401 | Unauthorized — no valid session |
| 500 | Failed to activate MCP. The error message describes the failure (for example, skill not found or server failed to start). |
Deactivate a skill MCP
Stops the MCP server for the specified skill and frees its resources.
Path parameters
| Parameter | Type | Required | Description |
|---|
skillId | string | Yes | Identifier of the skill whose MCP server to deactivate |
Response
{
"success": true,
"skillId": "websearch",
"message": "MCP deactivated"
}
| Field | Type | Description |
|---|
success | boolean | Whether deactivation succeeded |
skillId | string | The skill that was deactivated |
message | string | Confirmation message |
Errors
| Code | Description |
|---|
| 401 | Unauthorized — no valid session |
| 500 | Failed to deactivate MCP. The error message describes the failure. |
Automatic idle cleanup
MCP servers that remain idle are automatically deactivated to free resources. You do not need to manually deactivate servers that are no longer in use, though explicit deactivation is recommended when you know a skill’s tools are no longer needed.
