Endpoints & transport

Endpoints

Endpoint	Method	Purpose
`https://api.vibesell.it/v1/mcp`	`POST`	The MCP server — JSON-RPC over Streamable HTTP. Needs a bearer token.
`https://api.vibesell.it/.well-known/oauth-protected-resource/v1/mcp`	`GET`	Protected resource metadata (RFC 9728). Also served without the `/v1/mcp` suffix.
`https://api.vibesell.it/.well-known/oauth-authorization-server`	`GET`	Authorization server metadata (RFC 8414).
`https://api.vibesell.it/v1/oauth/register`	`POST`	Dynamic client registration (RFC 7591).
`https://api.vibesell.it/v1/oauth/authorize`	`GET`	Authorization — redirects to VibeSell’s consent page.
`https://api.vibesell.it/v1/oauth/token`	`POST`	Code exchange and refresh (OAuth 2.1).
`https://api.vibesell.it/v1/oauth/revoke`	`POST`	Token revocation (RFC 7009).

The discovery documents are cached for an hour (Cache-Control: public, max-age=3600). The authorization flow is described in Authorization.

Transport

Streamable HTTP, stateless. Each POST carries one JSON-RPC message, opens its own server instance with the access of its token, and closes it with the response. There is no session: no Mcp-Session-Id is issued.
No server push. GET (a notification stream) and DELETE (closing a session) answer 405 Method Not Allowed with Allow: POST.
Bearer token only. Authorization: Bearer <access token> — no cookie, no API key. Without one, the server answers 401 with a WWW-Authenticate challenge that points to the metadata.
Protocol versions. The server negotiates up to MCP 2025-11-25 and accepts earlier versions back to 2024-11-05.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.vibesell.it/.well-known/oauth-protected-resource/v1/mcp", scope="mcp mcp:act"

initialize

curl https://api.vibesell.it/v1/mcp \
-H "Authorization: Bearer $VIBESELL_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'

{
  "protocolVersion": "2025-11-25",
  "capabilities": {
    "tools": {},
    "resources": {}
  },
  "serverInfo": {
    "name": "vibesell",
    "title": "VibeSell",
    "version": "0.3.0",
    "description": "Your VibeSell workspace in the chat: leads, plans, sending setup, campaign and replies.",
    "websiteUrl": "https://vibesell.it",
    "icons": [
      {
        "src": "https://vibesell.it/brand/vibesell-icon.png",
        "mimeType": "image/png",
        "sizes": [
          "144x144"
        ]
      }
    ]
  },
  "instructions": "VibeSell finds B2B prospects and runs cold email campaigns for the user, from their VibeSell workspace. Start with get_w…"
}

The instructions differ for a read-only connection and for one that can act: see Server instructions.

tools/list

The list is built per token:

Tools	Listed when
Read tools (12)	Always.
Act tools (25)	The token carries `mcp:act`.
`decide_approval`	The token carries `mcp:act` and the client is the Claude app, which hides it from the model (`_meta.ui.visibility: ["app"]`).

Every tool comes with its inputSchema, its outputSchema, annotations and the card resource:

{
  "name": "estimate_lead_pool",
  "title": "Count matching leads",
  "description": "Count how many B2B leads (people at companies) VibeSell's lead provider holds for a target…",
  "inputSchema": {
    "type": "object",
    "properties": {
      "countries": {
        "…": "…"
      }
    }
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "kind": {
        "const": "lead_count"
      }
    }
  },
  "annotations": {
    "title": "Count matching leads",
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": true
  },
  "_meta": {
    "ui": {
      "resourceUri": "ui://vibesell/card-2f87d8dc967b"
    },
    "ui/resourceUri": "ui://vibesell/card-2f87d8dc967b"
  }
}

Annotation	Set from
`readOnlyHint`	`true` for read tools, `false` for act tools.
`destructiveHint`	Always `false`: nothing destructive runs without an approval card.
`idempotentHint`	Whether two identical calls give the same result.
`openWorldHint`	Whether the tool reaches a provider (leads, Instantly, Stripe).

resources

The server exposes one resource, the VibeSell card (text/html;profile=mcp-app), at ui://vibesell/card-2f87d8dc967b — the suffix is a hash of the card’s code. Any address matching ui://vibesell/card-{version} returns today’s card, so a client that cached an older tool list still gets a card. See Interactive cards.