MCP setup

Connect Ezra to your MCP client.

The current API-key endpoint is https://ezramcp.com/v1/mcp. Auth header is Authorization: Bearer ezra_live_…. JSON-RPC 2.0 over HTTP.

Get a key first

Claude Code

claude mcp add ezra https://ezramcp.com/v1/mcp \
  --header "Authorization: Bearer ezra_live_..."

Cursor / Cline / API-key clients

{
  "mcpServers": {
    "ezra": {
      "transport": "http",
      "url": "https://ezramcp.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ezra_live_..."
      }
    }
  }
}

The 11 legacy tools

get_verses_by_topic(topic, limit?) — primary lookup, returns verses with refs and text
list_topics(category?, limit?) — discovery; filter by theme / story / parable
get_pericope(name) — return a story or parable with its verses
find_topic(query) — fuzzy search topic names
get_related_topics(topic, limit?) — topics that co-occur with this one
get_jesus_teachings(mode?) — Jesus' beliefs, commands, or both, grounded in Gospel refs
create_verse_collection(...) — save refs, bible version, API.Bible tags, and global tags
get_verse_collection(id) — return an accessible collection without stored verse text
find_verse_collections(tag?, tag_source?) — find public and owned collections by tag
get_verse(ref) — single-verse lookup with topics and pericopes
get_chapter(book, chapter) — available chapter verses with per-verse topics

Example tool call

curl https://ezramcp.com/v1/mcp \
  -H "Authorization: Bearer ezra_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "get_verses_by_topic",
      "arguments": { "topic": "Forgiveness", "limit": 5 }
    }
  }'

Jesus beliefs and commands

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_jesus_teachings",
    "arguments": { "mode": "both" }
  }
}

Custom verse collections

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_verse_collection",
    "arguments": {
      "title": "Jesus commands",
      "visibility": "private",
      "bible_version": "WEB",
      "verse_refs": ["Matthew 22:37", "John 13:34"],
      "api_bible_tags": ["Jesus", "Commands"],
      "global_tags": ["daily-practice"]
    }
  }
}

The staged shared connection: up to 14 tools

POST https://ezramcp.com/mcp uses independent feature gates: art alone lists 1 tool, OAuth alone lists 13 protected tools, and both enabled list 14. This candidate is awaiting deployment and host connection testing. OAuth is disabled by default; the API-key snippets above do not provide ChatGPT OAuth setup.

When enabled, an OAuth-capable host links an existing Ezra account through Ezra's first-party sign-in and a separate consent screen. Free accounts are eligible. Enter a key only in Ezra's first-party form if that option is shown; never paste a key or email code into a conversation.

mcp:call permits Scripture and catalog calls.
mcp:call collections:read permits collection reads and searches.
mcp:call collections:write permits collection creation.

OAuth does not authorize account administration, API-key creation, or billing. Account signup stays in Account; OAuth sign-in proves an existing account.

Free devotional art on the shared route

get_devotional_art requires an existing account and mcp:call and is quota-exempt. It returns up to two native images with attribution when matching assets are available. Use one selector: art_id, pericope_id, pericope, or reference; limit is 1 or 2.

{
  "jsonrpc": "2.0", "id": 4, "method": "tools/call",
  "params": { "name": "get_devotional_art", "arguments": { "limit": 2 } }
}

The new local package prepares 4,706 artwork records as bounded display images with separate source and derivative lineage. Deployment/publication remain pending. The older optional preview packages only two fixture images; catalog metadata alone does not establish hosted availability. Supplied Scripture associations are qualified metadata, not proof of literal depiction or historical accuracy; visual review and expanded publication remain pending. Unmapped artwork can be selected by ID. A missing image or unsupported passage returns an honest availability error.

Monthly account limits

Free — 20 additional WEB tool calls per account per UTC month, at most one per UTC day
Pro — 10,000 per account per UTC month
Max — 100,000 per account per UTC month

The account allowance is shared across keys, OAuth clients, and both endpoints. Authorized dispatched calls, including lookup errors, count. Discovery (initialize and tools/list), authorization failures, and shared-route art are exempt. The shared route returns HTTP 429 with rate_limit_exceeded, tier, limit, and used; legacy rate-limit errors retain their existing JSON-RPC format.

Source data

World English Bible (public domain). Text lookup is limited to the currently loaded data; chapter lookup does not certify complete chapter coverage. Topic/story metadata and artwork rights have separate provenance. Artwork includes per-record rights and attribution; the source-code license does not license every image. See the project source and connection guide.

Daily WEB and paid translation selection

get_daily_passage takes no arguments and returns one fixed WEB verse for the server UTC day. Its seven-verse rotation repeats weekly at UTC midnight; repeat calls are free. Art and the daily verse require an existing account and mcp:call, but consume neither quota field.

Paid accounts can call list_available_translations for the configured API.Bible key’s current catalogue, then supply a returned translation_id to get_verse. Omission preserves WEB. Selected passages preserve original text and copyright/attribution and are bounded to eight same-chapter verses. This integration is disabled until separately configured; supported editions are not guessed.