# GetBible MCP 2.0

Read-only MCP access to all nine GetBible API contracts.
Project and API documentation: https://getBible.net
MCP usage documentation: https://getBible.net/mcp
Official public Streamable HTTP endpoint: https://mcp.getbible.net/
Use that root URL exactly; do not append /mcp or an API version. API versions are tool arguments.
Other GetBible MCP hosts use their own complete endpoint URLs.
Local transport: getbible-mcp --transport stdio. Both transports have the same tools, resources and
prompts. Python MCP SDK 2.2.0 implements protocol 2026-07-28.

Public access is free; no account or token is required by default. Anonymous MCP requests use the
same rate limits as public search. Honor HTTP 429 and Retry-After; use backoff when retrying.
Contact GetBible administrators for an optional token for MCP or any API endpoint. Configure an
issued token securely as Authorization: Bearer in the client; never put it in a URL or tool arguments.
See usage-policy.md for the limits and access details.

## Start here

- discover_apis: service/version catalog and authoritative OpenAPI URLs.
- describe_api_operation: list operations or inspect one operation's exact inputs/outputs/errors.
- call_api_operation: execute a described read-only operation, including search POST.
- resources/read getbible://docs/api: full integration guide.
- resources/read getbible://openapi/{service}/{version}: complete packaged OpenAPI contract.
- design_getbible_integration: integration planning prompt.

Services: api (v2/v3), query (v2/v3), search (v2/v3), dictionaries (v1), commentaries (v1),
bookmarks (v1). Operation IDs and argument names are scoped to the selected service/version.
Use parameters keyed by input_name; query.<name> disambiguates a name also used in the path.

## Convenience tools

- list_translations, list_books, list_chapters: discover metadata and valid coordinates.
- get_scripture: whole translation/book/chapter with before/after scope SHA-1 checks.
- query_verses: selected or grouped references; no fallback passage for invalid/missing references.
- search_verses: full-text search and upstream filters/pagination.
- get_hash, get_hash_manifest, check_for_updates: static scripture synchronization.
Scripture tools default api_version to v3. Choose v2 explicitly for upstream v2 data.

## Data and cache rules

Preserve native JSON and unknown fields. V3 tokens, spans, paragraph markers and lexical data must
not be flattened to v2. Retrieve rich translation metadata and rights from translation catalogs.
Discover dictionary IDs, entry IDs and commentary coverage; chapter/verse 0 can be introductions.
Bookmarks are public topics/references without scripture text or personal write operations.

The MCP keeps no persistent result cache. Query/search are non-cacheable by default. Downstream
caches must never exceed 30 days (2592000 seconds) and must obey shorter HTTP freshness, Age,
Expires, no-cache and no-store. Query/search TTL comes from HTTP headers, not a promised JSON field.
Search query.sha/query.cache are source/engine metadata, not result checksums. Static scripture uses
SHA-1; dictionary/commentary/bookmark manifests use SHA-256. Refresh atomically when hashes change.
Honor each translation/module's rights and provenance; the MCP software GPL does not relicense data.

## Documentation

This directory documents MCP package 2.0 and every supported upstream API version.

- Guide: api.md
- Examples: examples.md
- Cache policy: cache-policy.md
- Usage policy: usage-policy.md
- Manifest: manifest.json
- Tool catalog: tool-catalog.json

## Authoritative upstream OpenAPI documents

- https://api.getbible.net/v2/openapi.json
- https://api.getbible.net/v3/openapi.json
- https://query.getbible.net/v2/openapi.json
- https://query.getbible.net/v3/openapi.json
- https://search.getbible.net/v2/openapi.json
- https://search.getbible.net/v3/openapi.json
- https://dictionaries.getbible.net/v1/openapi.json
- https://commentaries.getbible.net/v1/openapi.json
- https://bookmarks.getbible.net/v1/openapi.json

Exact static copies: ../contracts/{service}-{version}.json
