Connect Basalt to your AI (MCP)

teambasaltv2

Basalt exposes an MCP server at https://app.basalt.cofoundy.ai/api/mcp. Connect it and your AI (Claude Code or Claude Cowork) can read, publish, and manage docs directly from chat — as you: you log in once via Cofoundy SSO (id.cofoundy.dev) and the AI inherits exactly your access (your vaults, your grants — nothing more).

One server, scoped by you. The same endpoint serves read, write, and admin tools. What you can actually do is decided by your grants, not by the connection — a teammate with read-only access sees the same tools but writes are refused.

Option A — Claude Code (CLI)

One command:

claude mcp add --transport http --scope user basalt https://app.basalt.cofoundy.ai/api/mcp
Use --scope user. It registers the connector for your user, so it's available in every Claude Code session/project — not just the current directory. Without it, claude mcp add defaults to local scope (this project only), and you'd have to re-add it in each repo.

The first time the AI uses a docs tool, Claude opens your browser to id.cofoundy.dev to authorize. If you're already logged in there, it's a one-click Approve (no password). After that it's silent.

Verify it's wired:

claude mcp list          # basalt should appear

Then in a Claude Code session, ask: "list my docs on Basalt" — it loads the connector and calls list_docs.

Headless / CI (no browser): use the static operator bearer instead of OAuth — claude mcp add --transport http --scope user basalt https://app.basalt.cofoundy.ai/api/mcp --header "Authorization: Bearer $DOCS_MCP_BEARER_TOKEN". The operator bearer covers read + write (Tier 0/1), never admin (Tier 2). Real end-user agents should use the OAuth (browser) path so writes are attributed to them.

Option B — Claude Cowork (desktop / web connector)

Step 1 — Open the Connectors menu

In Claude, open the chat + menu → Connectors → Add connector (or Manage connectors).

Step 2 — Add a custom connector

On the Connectors screen, hit + (top right) → Add custom connector.

Step 3 — Paste name + URL, then Add

  • Name: Basalt
  • URL: https://app.basalt.cofoundy.ai/api/mcp

Step 4 — Connect

The connector shows as Not connected. Hit Connect.

Step 5 — Authorize (one click)

Your browser opens the Cofoundy SSO authorize screen at id.cofoundy.dev. If you're already signed in there, you'll see your identity (Signed in as you@cofoundy.dev) — just hit Approve. No password.

Step 6 — Done

Claude confirms Connected to Basalt and lists the available tools. Close the browser tab and go back to chat.

The connector UI flow is identical to any custom MCP connector — only the Name and URL above are Basalt-specific.

Using it

Ask in natural language:

  • "list my docs / search docs for X" → list_docs / search_docs
  • "publish this as a doc on Basalt" → publish_doc (auto-compiles + lints; pass it markdown)
  • "pull doc X so I can edit it" → pull_doc → edit → republish (round-trip)
  • "upload this image to the doc" → upload_asset
  • "share doc X with the team / make it public" → set_access
Verification is built in. Every write auto-compiles + lints — broken or unsafe content is rejected with a clear error, soft issues come back as warnings. Add dry_run: true to a publish to pre-flight without publishing.

If the authorize screen asks for email + password

That means the browser where authorization opened doesn't have your id.cofoundy.dev session. Fix (10 s): in that same browser, open https://id.cofoundy.dev and sign in, then hit Connect again — now it's one-click.

Why: the desktop app opens authorization in your system browser. The SSO is one-click only if your Cofoundy session lives in that browser.