MCP server

Blobify exposes a Model Context Protocol server for AI hosts that support Streamable HTTP. The server provides typed tools for discovery, content authoring, assets, publishing, schemas, generated clients, locales, archives, and webhooks.

Endpoint and transport

POST https://api.blobify.io/v1/mcp
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

The endpoint is stateless. Each request creates a fresh MCP server and returns plain JSON. It does not use SSE or resumable sessions.

The same URL serves every organization. A manual API key grants one organization. An OAuth token can grant one or several organizations. Call listOrgs at the start of a session, and pass orgId on targeted calls when the token covers more than one organization.

Choose OAuth or an API key

Claude and ChatGPT can connect through Blobify's OAuth 2.1 flow. Add https://api.blobify.io/v1/mcp as a custom connector, sign in to Blobify, choose the organizations to share, and approve access. The connector receives a scoped token without asking you to paste a long-lived API key.

Use a manual API key for automation hosts that accept a bearer header, including Codex, Cursor, Zed, scripts, and local MCP bridges. Create the key in Settings > Developer > API Keys, assign the least privileged role, and restrict it to the required spaces.

OAuth-issued access follows the user's current organization membership. Manual keys use the role and spaces assigned when the key is created. Both can be revoked from Blobify.

Connect with a bearer header

For a client that accepts remote Streamable HTTP directly, configure this URL and header:

{
  "url": "https://api.blobify.io/v1/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}

Claude Desktop installations that need a stdio bridge can use mcp-remote:

{
  "mcpServers": {
    "blobify": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.blobify.io/v1/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Do not expose a manual API key in browser JavaScript. MCP clients send requests from their native application or hosted connector infrastructure.

Tool catalog

The current registry contains 44 tools. The names below match src/mcp/tools.registry.ts exactly.

Discovery and reads

Drafts, imports, and assets

Asset bytes go directly from the host to the presigned bucket URL. Upload the original file, then confirm it. Blobify stores originals and leaves resizing and cropping to delivery helpers.

Validation and lifecycle

Deletion is archive-first. Use restoreContent to recover the first delete. Permanent deletion is the second delete of an archived entry.

Schemas, locales, and code generation

Schema writes and rebuilds require developer or admin. Destructive schema operations and locale changes can require admin. Regenerate the client after any model or block schema change.

Webhooks

Call getWebhookSpec before implementing a receiver. Blobify includes resolved urls and revalidationTags in lifecycle payloads, retries a failed delivery once, and stores only the latest delivery result. It does not maintain a retry queue.

A safe authoring workflow

1. Call listOrgs, then getReadContext.
2. Read the relevant model or block schema.
3. Find and read the target content before changing it.
4. Prefer patchFields for a small edit and saveDraft for an intentional full replacement.
5. Call canPublish before publishing.
6. Publish only when the user's request clearly includes publishing.

For a block append, the tool input separates the block type from its field values:

{
  "model": "page",
  "id": "page_1",
  "blocksField": "sections",
  "block": {
    "type": "hero-block",
    "fields": {
      "heading": { "en": "Welcome" }
    }
  }
}

appendBlock supplies the block instance ID. Before calling it, read both the model and block schemas so the chosen block is allowed and its required fields are present.

Reads for applications

MCP read tools are useful while an AI host is authoring content. Production websites should use generateClient and read published JSON directly from the bucket. The generated client follows summary manifests, content prefixes, asset resolution, references, and list-index v2 pages.

Troubleshooting

A client tries to parse SSE

Choose Streamable HTTP and expect an application/json response. Blobify does not return an SSE stream.

resources/list returns method not found

Blobify exposes MCP tools, not MCP resources. Use tools/list.

A call returns 401

The token is missing, malformed, expired, or revoked.

A call returns 403

The current role does not permit that tool, the target space is outside the token's scope, or an OAuth user's live membership no longer grants access.

The host cannot fetch a presigned or bucket URL

Use findContent, getContent, and findAssets for normal authoring reads. Asset and import uploads still require the host to perform an HTTP PUT to the presigned URL.