How to connect Claude/ChatGPT to B1 via MCP with an API key?

[fblanker]

Hi! I've created an API key in B1 Admin and would like to connect Claude to our church's B1 data via the MCP server I understand is built into the B1 API. I can't find the MCP server URL or setup instructions in B1 Admin or on support.churchapps.org.

Could you tell me:

What is the MCP server URL?
How should the API key be passed (header name, bearer token, or OAuth)?
Which permissions does the key need for service plans and songs?

Thanks for the great work on B1!

[Erfouni]

The MCP server is built into the B1 API and it is documented, just under the developer docs rather than in B1 Admin: MCP Server and API Keys (both are also under Developer → API on the support site).

URL: https://api.churchapps.org/mcp. It's MCP Streamable HTTP, POST only, and stateless.

Authentication: the key goes in a bearer header:

Authorization: Bearer cak_<prefix>.<secret>

There is no OAuth on the MCP endpoint, and that decides which client you can use. The MCP docs say the endpoint doesn't publish OAuth discovery metadata, so Claude.ai's "Add custom connector" and ChatGPT's Connectors can't connect to it directly. Clients that let you set a static header work: Claude Code, Claude Desktop, Cursor, the OpenAI Agents SDK.

Claude Code:

claude mcp add --transport http b1 https://api.churchapps.org/mcp --header "Authorization: Bearer cak_..."

Claude Desktop, through the mcp-remote bridge (needs Node.js). Putting the whole header value in an env var avoids problems with spaces in arguments on Windows:

{
  "mcpServers": {
    "b1": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.churchapps.org/mcp", "--header", "Authorization:${B1_AUTH}"],
      "env": { "B1_AUTH": "Bearer cak_..." }
    }
  }
}

Permissions for service plans and songs:

• A key acts as the person who created it, narrowed by its scopes. A key with no scopes has that person's full permissions. Scopes can only narrow; they never add a permission the person doesn't have.
• Songs are under /content/songs and /content/arrangements. Listing, creating, importing and deleting songs checks Edit Content, which the content:write scope carries.
• Service plans are under /doing/plans. B1's permission for plans is Edit Plans (the "Forms and Plans" section of a role). The scope table in the docs has no plans entry, but the API's scope list does include a plans scope (kept for FreeShow sync) that carries Edit Plans, Edit Content and Edit Schedules. GET /membership/apiKeys/scopes returns every scope name.

So a working setup is a key with scopes plans content:write, created by a person whose role has Edit Plans and Edit Content. The API Keys page recommends a dedicated service-account person rather than a staff member's own login, so the key keeps working if that person leaves. Keys are made in Settings → Developer → API Keys, and the full key is shown only once.

Once connected, ask the assistant to call list_endpoints with the filter plans or songs. It returns the exact routes and the scopes each one likely needs, and describe_endpoint shows the payload for any of them.