AI Coach API

List and search published MCP servers with cursor-based pagination.

curl "https://aicoach.pw/api/v1/mcp/servers?search=postgres&limit=10"

{
  "servers": [
    {
      "server": {
        "name": "io.github.user/postgres-mcp",
        "title": "PostgreSQL MCP",
        "description": "Query PostgreSQL databases via MCP",
        "version": "1.2.0"
      },
      "_meta": {
        "io.modelcontextprotocol.registry/official": {
          "status": "active",
          "publishedAt": "2025-06-01T00:00:00Z",
          "updatedAt": "2025-07-15T12:00:00Z",
          "isLatest": true
        },
        "aicoach.pw": {
          "id": "uuid-...",
          "slug": "postgres-mcp",
          "external_id": null,
          "transport": "stdio",
          "approved": true,
          "visibility": "public",
          "detailUrl": "https://aicoach.pw/mcp/postgres-mcp"
        }
      }
    }
  ],
  "metadata": { "count": 1, "nextCursor": null }
}

Publish a new MCP server or update an existing one. Upsert behavior: if a server with the same name or slug already exists for your account, it is updated instead of duplicated.

{
  "name": "com.example/my-server",
  "title": "My MCP Server",
  "description": "Brief description of the server",
  "version": "1.0.0",
  "transport": "stdio",
  "external_id": "your-internal-ref-123",
  "repository": {
    "url": "https://github.com/user/repo",
    "source": "github"
  },
  "command": "npx",
  "websiteUrl": "https://example.com"
}

{
  "server": {
    "name": "com.example/my-server",
    "title": "My MCP Server",
    "description": "Brief description of the server",
    "version": "1.0.0"
  },
  "_meta": {
    "io.modelcontextprotocol.registry/official": {
      "status": "active",
      "publishedAt": "2026-04-02T00:00:00Z",
      "updatedAt": "2026-04-02T00:00:00Z",
      "isLatest": true
    },
    "aicoach.pw": {
      "id": "uuid-...",
      "slug": "com.example--my-server",
      "external_id": "your-internal-ref-123",
      "transport": "stdio",
      "approved": false,
      "visibility": "private",
      "detailUrl": "https://aicoach.pw/mcp/com.example--my-server"
    }
  }
}

{
  "error": "Duplicate name or slug",
  "message": "A server with this name or slug already exists (slug: com.example--my-server)",
  "existing": {
    "server": { "name": "...", "title": "...", ... },
    "_meta": { ... }
  }
}

Get full details for a single MCP server by its URL slug.

curl "https://aicoach.pw/api/v1/mcp/by-slug/filesystem"

List all versions of a server, ordered by publish date (newest first).

curl "https://aicoach.pw/api/v1/mcp/servers/com.example%2Fmy-server/versions"

Update status across all versions of a server at once.

{
  "status": "deprecated",
  "statusMessage": "Use v2 instead"
}

Update status for a single version. Same request body as above. Returns 400 if the status is already set to the requested value.

List and search skills with optional filtering.

curl "https://aicoach.pw/api/v1/skills/list?q=commit&limit=5"

List all skill categories with slugs and skill counts.

Get full skill details including install command and SKILL.md URL.

curl "https://aicoach.pw/api/v1/skills/commit"

PKCE Auto-Registration Flow

Your App                          AI Coach                GitHub
  │                                  │                       │
  ├─① POST /api/v1/oauth/register──►│                       │
  │  { client_name, redirect_uris } │                       │
  │◄── { client_id } ──────────────┤                       │
  │                                  │                       │
  ├─② Redirect user ────────────────┼──► GitHub OAuth ──►  │
  │                                  │  ◄── session cookie ──┤
  │                                  │                       │
  ├─③ POST /api/v1/oauth/authorize─►│                       │
  │  { client_id, code_challenge }  │                       │
  │◄── { code } ───────────────────┤                       │
  │                                  │                       │
  ├─④ POST /api/v1/oauth/token ───►│                       │
  │  { code, code_verifier }        │                       │
  │◄── { api_key } ────────────────┤                       │
  │                                  │                       │
  ├─⑤ POST /api/v1/mcp/publish ───►│                       │
  │  Authorization: Bearer mcp_xxx  │                       │
  │◄── { server, _meta } ──────────┤                       │

Multi-Tenant Isolation

One client_id per app, many users. Each user authenticates separately and gets their own API key. Server ownership is enforced by the user's GitHub identity — User A cannot modify User B's servers.

Confidential Client Flow

For backend services that can securely store a client_secret. Register manually at /account/apps (requires publisher status).

1. 1

   Register at /account/apps to get client_id + client_secret.

2. 2

   Redirect user to authorize:

   https://aicoach.pw/connect?client_id=YOUR_ID&redirect_uri=YOUR_CALLBACK&state=RANDOM

3. 3

   User approves. Your callback receives a code parameter.

4. 4

   Exchange code for API key (backend-to-backend):

   {
     "code": "a1b2c3d4e5f6...",
     "client_id": "ocp_xxxxx",
     "client_secret": "ocs_xxxxx",
     "redirect_uri": "https://myapp.com/callback"
   }

Both flows use the same /api/v1/oauth/token endpoint. Provide client_secret instead of code_verifier.

List all MCP servers owned by the authenticated user.

curl https://aicoach.pw/api/publisher/mcp-servers \
  -H "Authorization: Bearer mcp_xxxxx"

Create a new MCP server. Starts as draft (approved=false).

{
  "serverName": "com.example.my-server",
  "slug": "my-server",
  "version": "1.0.0",
  "displayName": "My Awesome Server",
  "descriptionShort": "Brief description (max 160 chars)",
  "transport": "stdio"
}

Update server metadata. Send approved: true to publish.

Delete an MCP server permanently.

HTTP Status Codes

Rate Limits