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://auth.aws-dev.streamsappsgslbex.com/mcp

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

Auth: OAuth 2.1 with PKCE (Bearer token)

SDK: @modelcontextprotocol/sdk ^1.25.1

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://auth.aws-dev.streamsappsgslbex.com/mcp",
      "transport": "streamable-http",
      "auth": {
        "type": "oauth",
        "authorization_url": "https://auth.aws-dev.streamsappsgslbex.com/authorize",
        "token_url": "https://auth.aws-dev.streamsappsgslbex.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://auth.aws-dev.streamsappsgslbex.com/mcp.

Discovery Endpoints

Endpoint	Description
GET .well-known/oauth-authorization-server	OAuth 2.1 server metadata (RFC 8414)
GET .well-known/openid-configuration	OpenID Connect discovery
GET .well-known/jwks.json	JSON Web Key Set for token verification
GET .well-known/oauth-protected-resource	Protected resource metadata (RFC 9728)
GET /register	Dynamic Client Registration (RFC 7591)
GET /tools	Public tool listing (no auth required)
GET /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.aws-dev.streamsappsgslbex.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 1 hour; use refresh tokens for renewal
Dynamic Client Registration is supported per RFC 7591

Sessions

The server uses the mcp-session-id header to maintain MCP protocol state across requests. Sessions are bound to the authenticated user for security.

Sessions are created automatically on the first request
The server echoes the session ID in the response header—clients should persist it
Sessions expire after 30 minutes of inactivity
Presenting an invalid or expired session returns 401
Sessions are user-bound—a session ID is useless without the user's OAuth token

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
401	Invalid or expired session	Drop mcp-session-id header to start a new session
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).