MCP server

Connect

Connect ChatGPT, Claude, or another remote MCP client to your Bidama host. The server URL is the public origin plus /mcp.

Remote MCP URL: https://<your-host>/mcp

• HTTP is sessionless: each POST builds a temporary server from that request's OAuth access token. Unsafe cross-origin browser requests are rejected. Authenticated GET returns 405.
• ChatGPT and Claude should be configured with https://<your-host>/mcp, then complete the browser OAuth consent flow.
• Tool permissions are read, write, and delete. offline_access is only an authorization-server scope for refresh tokens.
• JSON-RPC batch arrays are rejected before dispatch so one transport request cannot fan out into unbounded tool calls.
• Each replica accepts at most four concurrent MCP HTTP requests and two per OAuth access token (429 + Retry-After beyond either bound). A POST body must finish within 60 seconds.

Tools

Four tools preserve authorization boundaries. Creation and change stay separate; delete is never mixed into write.

Annotations are client hints, never authorization. bidama_create is openWorld because Notion create can schedule an external fetch; the other tools operate only on this deployment.

bidama_read

Requires read. Select exactly one closed operation branch:

• type filters: link, markdown, file, image, collection, notion, bio, artifact. sort: newest, pinned, title, expiring, most_viewed, recently_updated. archived: false (default), true, or all.
• List rows omit owner IDs, internal object keys, and large bodies. Fetch get_resource for full public resource details.

bidama_create

Requires write. type selects one of eight closed branches. Unknown fields are rejected.

• Common optional fields: slug, title, description, expires_at, password, labels.
• file_content is base64. The server sniffs MIME: image requires image bytes and file requires non-image bytes.
• Artifacts accept exactly one of archive_base64 (ZIP) or files as a native JSON array of {path, content, encoding?} — never a stringified JSON string, and never both modes. Prefer archive_base64 for multi-file packages when arrays are awkward. Decoded content is capped at 8 MiB; direct mode at most 500 files. visibility is public (default), unlisted, or private. max_views is not supported.
• Results return slug, type, url, and etag, plus essentials such as stored filename or artifact deployment_id, origin_url, and entry_path.

bidama_change

Requires write. Annotated destructive because branches can replace originals or retire deployments.

• slug always identifies the current resource; new_slug is the replacement value on rename.
• Poll optimize jobs with bidama_read operation get_job. On job_already_active, reuse the earlier job_id rather than enqueueing again.

bidama_delete

Requires delete and accepts slug. Soft-deletes the owned resource so the slug stops resolving publicly. Success returns {slug, deleted: true}. Annotated idempotent: a safe retry may report not_found.

Example calls

Tools take a discriminator (type or operation). Keep the returned etag for later edits. For artifacts, files must be a real JSON array (see the second example), not a string.

bidama_create
{
  "type": "markdown",
  "title": "Release notes",
  "raw_markdown": "# Hello\n\nShipped today."
}

bidama_create
{
  "type": "artifact",
  "title": "Demo",
  "files": [
    {"path": "index.html", "content": "<h1>Hi</h1>", "encoding": "text"}
  ]
}

bidama_change
{
  "operation": "update_resource",
  "slug": "release-notes",
  "if_match": "<etag-from-get_resource>",
  "title": "Release notes (final)"
}

bidama_read
{
  "operation": "get_job",
  "job_id": "<job-id-from-optimize_original>"
}

Conventions

• Omit slug on create to auto-generate one. Slugs are 3–64 characters: a–z, 0–9, - or _.
• get_resource returns an etag; pass it as if_match on bidama_change to avoid overwriting concurrent edits.
• Inline file and artifact payloads are capped at 8 MiB decoded (12 MiB MCP JSON envelope). Use REST uploads for larger content.
• Outputs include typed structuredContent plus a compact JSON text copy for clients that ignore structured output.
• The machine-readable REST contract is also available as MCP resource (text/yaml): bidama://openapi.yaml

Errors and recovery

Failures keep the REST envelope (status, error_code, message, field/details, Retry-After) and append a short recovery hint for stable codes:

Deliberately not exposed

• No list_jobs — agents poll job IDs returned by their own operations.
• QR bytes are not returned as tool content; use the resource QR URL out of band.
• Cookie-API-only bio blocks, collection items, upload requests, and Notion cached-page ops are not MCP tools.
• No generic REST passthrough tool — typed schemas, annotations, and projections stay mandatory.

ChatGPT and Claude

In ChatGPT, Claude, or any remote MCP client, add a custom connector with this server URL and approve the requested scopes in Bidama.

{
  "name": "Bidama",
  "url": "https://<your-host>/mcp"
}

Revoke previously approved clients from Connected Apps: /connected-apps.

Also see: API · OpenAPI