MCP Server Documentation

Model Context Protocol (MCP) integration for NuBerea — connect AI assistants like ChatGPT, Claude, and Cursor to Biblical study tools.

Overview

The NuBerea MCP server exposes Biblical study capabilities as tools and resources that any MCP-compatible client can use. It follows the Model Context Protocol specification with Streamable HTTP transport and OAuth 2.1 authentication.

Endpoint: https://mcp.nuberea.com/mcp

Transport: Streamable HTTP (JSON-RPC 2.0 over POST)

Auth: OAuth 2.1 with PKCE (Bearer token)

Client SDK: @modelcontextprotocol/client 2.0

Connection

Configure your MCP client to connect to the NuBerea server. Most clients support JSON configuration:

MCP Client Configuration (e.g. Claude Desktop, Cursor)

{
  "mcpServers": {
    "nuberea": {
      "url": "https://mcp.nuberea.com/mcp",
      "transport": "streamable-http",
      "auth": {
        "type": "oauth",
        "authorization_url": "https://auth.nuberea.com/authorize",
        "token_url": "https://auth.nuberea.com/token",
        "client_id": "YOUR_CLIENT_ID",
        "scope": "openid mcp"
      }
    }
  }
}

For ChatGPT / OpenAI Actions, configure the OAuth settings in the GPT builder and point the MCP endpoint to https://mcp.nuberea.com/mcp.

Discovery Endpoints

Endpoint	Description
GET https://auth.nuberea.com/.well-known/oauth-authorization-server	OAuth 2.1 server metadata (RFC 8414)
GET https://auth.nuberea.com/.well-known/openid-configuration	OpenID Connect discovery
GET https://auth.nuberea.com/.well-known/jwks.json	JSON Web Key Set for token verification
GET https://auth.nuberea.com/.well-known/oauth-protected-resource	Protected resource metadata (RFC 9728)
GET https://auth.nuberea.com/register	Dynamic Client Registration (RFC 7591)
GET https://mcp.nuberea.com/tools	Public tool listing (no auth required)
GET https://mcp.nuberea.com/health	Health check

Authentication

The MCP server uses OAuth 2.1 with PKCE (Authorization Code flow). Users authenticate via NuBerea's Firebase-backed login, then the OAuth bridge issues MCP access tokens.

OAuth Flow

Authorization Request — Client redirects user to /authorize with PKCE challenge
User Login — User authenticates with Firebase credentials on NuBerea
Authorization Code — Server redirects back with a one-time code (expires in 10 min)
Token Exchange — Client exchanges code + PKCE verifier at /token for access & refresh tokens
MCP Requests — Client sends POST /mcp with Authorization: Bearer <token>

Example: Token Exchange

POST https://auth.nuberea.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<your_callback_url>
&client_id=<your_client_id>
&code_verifier=<original_pkce_verifier>

Security notes:

PKCE (S256) is mandatory on all authorization requests
Authorization codes are single-use and expire after 10 minutes
Access tokens expire after 15 minutes; refresh tokens rotate on every renewal
Dynamic Client Registration is supported per RFC 7591

Tools

The server exposes 18 built-in, read-only tools. Use GET /tools for the live schemas and availability metadata.

Bible and text search

bible_getbible_list_bookssearch_text

Morphology

query_versesearch_morphologyget_word_by_ref

Lexicons

lexicon_lookuplexicon_search

Syntax

syntax_get_sentence_treesyntax_get_constituentssyntax_get_token_path

Synoptic parallels

synoptic_find_parallelssynoptic_searchsynoptic_list_pericopes

Manuscript transcriptions

transcription_cntr_get_versetranscription_cntr_list_manuscripts

Relationship graph

graph_expandgraph_list_edge_types

Bible text and Synoptic parallels are available without a paid plan. Original-language corpora, lexicons, syntax, manuscripts, graph traversal require a paid plan.

Errors

The MCP endpoint validates requests strictly before processing:

Status	Condition	Resolution
400	Invalid JSON-RPC envelope	Ensure body has jsonrpc: "2.0", method, and valid id
401	Missing / invalid / expired token	Re-authenticate via OAuth flow
413	Request body > 256 KB	Reduce payload size
415	Content-Type not application/json	Set Content-Type: application/json

Corpus data from Macula Hebrew and Macula Greek by Clear Bible, Inc. (CC BY 4.0). Lexicon data derived from the Perseids Project LSJ dataset (CC BY-SA 3.0).