How skil.ski speaks MCP.
Full protocol reference: JSON-RPC methods, authentication, rate limits, and error codes.
What is MCP?
Model Context Protocol (MCP) is an open standard that lets AI models call external tools using a simple JSON-RPC 2.0 over HTTP transport. It was designed to be the universal plug between an AI client (Claude, Cursor, ChatGPT, etc.) and any server that can answer capability requests.
An MCP server exposes a list of tools — each with a name, description, and JSON Schema for its inputs. The AI client discovers them with tools/list and invokes them with tools/call. The server executes the tool and returns the result as a structured content array.
skil.ski implements MCP protocol version 2025-03-26 at a single endpoint. Your token scopes the response to the skills your account has access to — the same URL serves everyone.
Why MCP matters for AI agents
Endpoint
https://skill.ski/api/mcpAll methods are sent as POST with a JSON body. The legacy GET manifest (MCP v1 format) is also available at the same URL with a GET request, but new integrations should use the JSON-RPC POST path.
Authentication
All requests require a bearer token in the Authorization header. Tokens are generated in your SkiLodge.
Authorization: Bearer sk_YOUR_TOKEN_HEREMethods
initializeProtocol handshake. Send once when opening a new connection. Returns the server protocol version and capabilities.
POST https://skill.ski/api/mcp
Authorization: Bearer sk_YOUR_TOKEN
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {
"name": "my-agent",
"version": "1.0.0"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-03-26",
"capabilities": {
"tools": { "listChanged": false }
},
"serverInfo": {
"name": "skil.ski",
"version": "2.0.0"
}
}
}tools/listReturns all tools your token has access to — first-party Skilskis, SkiRun pak tools, and any connected federated origins. Input schemas are included so your client can build correct arguments.
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"tools": [
{
"name": "dental-billing-claim-builder",
"description": "Builds a clean ADA claim form from treatment notes. Outputs CDT codes, fee schedule validation, and a submission-ready claim packet.",
"inputSchema": {
"type": "object",
"properties": {
"context": {
"type": "string",
"description": "Treatment notes, patient insurance info, and procedure details"
}
},
"required": ["context"]
}
},
{
"name": "skirun__pro_tech",
"description": "SkiRun for the Pro Tech Pak — orchestrates all tech skills in parallel for dev-team workflows.",
"inputSchema": {
"type": "object",
"properties": {
"context": { "type": "string" }
},
"required": ["context"]
}
}
]
}
}tools/callExecutes a Skilski by name. Pass the tool name and a contextstring with the relevant details from the user's conversation. The server returns a content array.
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "dental-billing-claim-builder",
"arguments": {
"context": "Patient: John Doe, DOB 1982-03-14. Insurance: Delta Dental Premier. Procedures today: D2740 (crown, porcelain, tooth #30), D0330 (panoramic image). Provider: Dr. Smith NPI 1234567890."
}
}
}{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "ADA Claim Draft\n\nPatient: John Doe | DOB: 03/14/1982\nProvider NPI: 1234567890\nInsurance: Delta Dental Premier\n\nLine items:\n D2740 — Crown, porcelain fused high noble metal, tooth #30\n Fee: $1,450 | Estimated patient portion: $435 (Delta Premier 70/30 major)\n D0330 — Panoramic radiographic image\n Fee: $185 | Estimated patient portion: $18.50 (preventive 90/10)\n\nTotal billed: $1,635 | Estimated patient balance: $453.50\n\nNext: attach X-rays for D2740 medical necessity. Claim flagged for pre-auth review per plan guidelines.\n\n[HUMAN REVIEW REQUIRED — verify CDT codes and fee schedule before submission]"
}
],
"isError": false
}
}Rate limits
Exceeded limits return HTTP 429 with a Retry-After header. Invocation logging does not count toward rate limits.
Error codes
Errors follow the JSON-RPC 2.0 error object format. Standard codes plus skil.ski extensions:
{
"jsonrpc": "2.0",
"id": 4,
"error": {
"code": -32000,
"message": "Origin \"my_origin\" not in a callable trust state (pending_review)",
"data": null
}
}HTTP 401 is returned for missing or invalid tokens before the JSON-RPC layer is reached. HTTP 429 for rate limit exceeded. All other protocol errors use HTTP 200 with the JSON-RPC error object in the body.