Partner MCP Gateway

Server URL

POST https://mcp.knotie-ai.pro/api/partner-mcp

Single Streamable-HTTP endpoint — accepts POST (JSON-RPC), GET (server-initiated SSE), and DELETE (session termination). Protected Resource Metadata is served at /.well-known/oauth-protected-resource/api/partner-mcp.

Authentication

Use your partner pkt_ API key (create one in Partner → Settings → API Keys) in the standard Authorization: Bearer header.

Authorization: Bearer pkt_<your-64-hex-secret>
Accept: application/json, text/event-stream
Content-Type: application/json
MCP-Protocol-Version: 2025-11-25

Keys can be scoped (read, read-write, or full access) per domain. See the scope picker on each key in the dashboard, or use the PATCH /api/partner/api-keys/:keyId/mcp-scopes endpoint.

Quick start — MCP client configs

{
  "mcpServers": {
    "knotie-partner": {
      "url": "https://mcp.knotie-ai.pro/api/partner-mcp",
      "headers": {
        "Authorization": "Bearer pkt_YOUR_KEY"
      }
    }
  }
}

{
  "serverUrl": "https://mcp.knotie-ai.pro/api/partner-mcp",
  "transport": "http",
  "authentication": {
    "type": "bearer",
    "token": "pkt_YOUR_KEY"
  }
}

{
  "mcpServers": {
    "knotie": {
      "url": "https://mcp.knotie-ai.pro/api/partner-mcp",
      "headers": {
        "Authorization": "Bearer pkt_YOUR_KEY"
      }
    }
  }
}

curl -X POST https://mcp.knotie-ai.pro/api/partner-mcp \
  -H 'Authorization: Bearer pkt_YOUR_KEY' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "meta_whoami",
      "arguments": {}
    }
  }'

Scope model

Every tool declares a required scope like customers:read or vps:write. An API key can hold any of:

• * — full access (default for existing keys)
• domain:* — read + write for a domain (e.g. vps:*)
• domain:read / domain:write — specific actions

Meta tools (meta_whoami, meta_scopes, meta_health) require no scope and always work. Restricted keys only see allowed tools in tools/list; a disallowed tools/call returns HTTP 403.

Tool catalog (135 tools, 15 scope domains + unscoped meta)

Call tools/list against the endpoint to enumerate the full catalog for your key (filtered by scope).

Protocol lifecycle

1. 1.initialize — handshake + protocol version negotiation. Server responds with serverInfo and capabilities.
2. 2.notifications/initialized — one-way client notification (server responds 202 Accepted).
3. 3.tools/list — returns tools visible to this key.
4. 4.tools/call — executes the tool and returns the result (JSON text).

Troubleshooting

Every error includes a structured data.type. Most common failure modes and fixes:

# Main app:
echo -n "$ENCRYPTION_KEY" | sha256sum
echo -n "$JWT_SECRET"     | sha256sum

# Connect Hub:
echo -n "$MAIN_APP_ENCRYPTION_KEY" | sha256sum
echo -n "$MAIN_APP_JWT_SECRET"     | sha256sum

# Corresponding pairs MUST match byte-for-byte.

Error semantics

Example — agent deploys a VPS stack for a customer

An AI agent can orchestrate the full turnkey flow a human partner does through the VPS dashboard — purchase a plan, pick apps from the catalog, deploy a combo, grant customer SSH access, all in one conversation.

1. 1. Discover what's deployable
   tools/call → vps_applications_list  •  vps_plans_list
2. 2. (Optional) Create a reusable package SKU
   vps_packages_create with { bundledAppIds: ["n8n","supabase","redis"], basePlanId, priceMonthlyUsd }
3. 3. Purchase the VPS
   vps_checkout with { planId, region, displayName, customerId } → returns Stripe checkout URL (hand to customer) or auto-provisions if pre-paid credits cover it.
4. 4. Deploy apps onto the fresh instance
   vps_instance_reinstall with { instanceId, applicationIds: ["n8n","supabase","redis"] } — wipes the image and composes the stack in one call.
5. 5. Surface credentials to the customer
   vps_instance_credentials (emails root password + IP), then vps_customer_access_grant to wire up SSH host/port/user for the customer portal.
6. 6. Assign / rename / change status later
   vps_instance_update handles rename, customer re-assignment, status (active / suspended / cancelled), and IP changes.

All six steps go through the same /api/partner/vps/* endpoints the dashboard uses — no parallel provisioning pipeline. Billing + Contabo + customer emails fire exactly as they would from a manual flow.

Example — list your customers

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "customers_list",
    "arguments": { "page": 1, "limit": 20 }
  }
}

{
  "success": true,
  "data": [ /* ...customer rows... */ ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalCount": 92,
    "limit": 20,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}