> ## Documentation Index
> Fetch the complete documentation index at: https://urantia.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Servers - Give AI Agents Access to the Urantia Book

> Connect Claude Desktop, Cursor, Windsurf, and other AI agents to the Urantia Papers API and documentation via MCP. 19 tools, 2 resource templates, 2 prompts — zero setup.

There are two MCP servers available — one for accessing Urantia Book data directly, and one for searching this documentation site.

| Server              | URL                   | Capabilities                     | Purpose                                                                      |
| ------------------- | --------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
| **API MCP Server**  | `api.urantia.dev/mcp` | 19 tools, 2 resources, 2 prompts | Search, paragraphs, entities, audio, Bible (WEB) + UB↔Bible cross-references |
| **Docs MCP Server** | `urantia.dev/mcp`     | 1 tool                           | Search the documentation site                                                |

## API MCP Server

The Urantia Papers API includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that exposes API endpoints as tools, papers/entities as resources, and study workflows as prompts that any AI agent can use natively.

```
https://api.urantia.dev/mcp
```

### Listed in the official registries

This server is published in the canonical registries that MCP-aware clients query for discovery:

* **[MCP Registry](https://registry.modelcontextprotocol.io)** (Anthropic-stewarded, official) — `dev.urantia/urantia-papers`. Verifiable: `curl "https://registry.modelcontextprotocol.io/v0/servers?search=urantia"`
* **[Smithery](https://smithery.ai/servers/urantiahub/urantia-papers)** — community marketplace with one-click install + 100/100 quality score

[![smithery badge](https://smithery.ai/badge/urantiahub/urantia-papers)](https://smithery.ai/servers/urantiahub/urantia-papers)

### One-click install via Smithery

The fastest way to add this server to your MCP client is via [Smithery](https://smithery.ai/servers/urantiahub/urantia-papers) — it generates the right config snippet for your client and handles the install.

### Manual setup

Add the server to your MCP client config directly. No API key, no installation, no build step.

<Tabs>
  <Tab title="Claude Desktop">
    Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

    ```json theme={null}
    {
      "mcpServers": {
        "urantia-papers": {
          "url": "https://api.urantia.dev/mcp"
        }
      }
    }
    ```

    Restart Claude Desktop. You'll see 19 tools available.
  </Tab>

  <Tab title="Claude Code">
    Add to `.mcp.json` in your project root:

    ```json theme={null}
    {
      "mcpServers": {
        "urantia-papers": {
          "url": "https://api.urantia.dev/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor / Windsurf">
    Add to your MCP settings:

    ```json theme={null}
    {
      "mcpServers": {
        "urantia-papers": {
          "url": "https://api.urantia.dev/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

Works with any client that supports [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).

### Available Tools

The MCP server exposes 19 tools using dot-notation names organized into a navigable namespace tree. All tools advertise read-only annotations and ship with output schemas for structured responses.

#### Structure & Navigation

| Tool              | Description                                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| `toc.get`         | Get the full table of contents — all 4 parts and 197 papers. Best starting point. |
| `papers.list`     | List all 197 papers with metadata (id, title, partId, labels).                    |
| `papers.get`      | Get a single paper with all its paragraphs. Supports `include_entities`.          |
| `papers.sections` | Get all sections within a paper, ordered by section number.                       |

#### Paragraphs

| Tool                 | Description                                                                              |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `paragraphs.get`     | Look up a paragraph by reference. Supports 3 formats: `"1:2.0.1"`, `"2:0.1"`, `"2.0.1"`. |
| `paragraphs.context` | Get a paragraph with N paragraphs before and after (configurable `window`, 1-10).        |
| `paragraphs.random`  | Get a random paragraph. Great for exploration.                                           |

#### Search

| Tool              | Description                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------- |
| `search.fulltext` | Full-text search. Modes: `and` (default), `or`, `phrase`. Filters: `paper_id`, `part_id`. |
| `search.semantic` | Semantic similarity search via vector embeddings. Finds conceptually related passages.    |

#### Entities

| Tool                  | Description                                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `entities.list`       | Browse 4,400+ entities (beings, places, orders, races, religions, concepts). Filter by `type` or search by `q`. |
| `entities.get`        | Get entity details: name, type, aliases, description, related entities, citation count.                         |
| `entities.paragraphs` | Get all paragraphs that mention a specific entity.                                                              |

#### Audio

| Tool        | Description                                                        |
| ----------- | ------------------------------------------------------------------ |
| `audio.get` | Get audio file URLs for a paragraph. Accepts any reference format. |

#### Bible (World English Bible)

| Tool                            | Description                                                                                                          |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `bible.books`                   | List all 81 books (39 OT + 15 deuterocanonical + 27 NT) with OSIS codes, canon, chapter counts.                      |
| `bible.book`                    | Get a single book's metadata. Accepts OSIS, USFM, full names, and aliases (case-insensitive).                        |
| `bible.chapter`                 | Get all verses in a chapter, ordered by verse number.                                                                |
| `bible.verse`                   | Get a single verse by `bookCode`, `chapter`, `verse`.                                                                |
| `bible.verse.urantia_parallels` | Reverse cross-reference — top-10 Urantia paragraphs semantically nearest a Bible verse.                              |
| `bible.search.semantic`         | Live semantic search over all 38,034 Bible verses; results arrive with their nearest UB paragraphs already attached. |

### Cross-reference enrichment on existing tools

`paragraphs.get`, `paragraphs.random`, `search.fulltext`, and `search.semantic` accept two optional booleans that attach pre-computed semantic neighbors to each result:

| Param                       | What you get                                                                           |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `include_bible_parallels`   | Top-10 Bible verses semantically nearest each UB paragraph.                            |
| `include_urantia_parallels` | Top-10 Urantia paragraphs semantically nearest each UB paragraph (UB ↔ UB "see also"). |

Both can be combined. Parallels are pre-computed via `text-embedding-3-large` cosine similarity, so adding them is cheap. Note: these are *semantic* neighbors, not curated linguistic parallels (e.g. Faw's Paramony) — best results trend conceptual rather than verse-citation.

### Resources

In addition to tools, the server exposes two resource templates clients can read directly:

| URI Template            | Description                                                                                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `urantia://paper/{id}`  | A single paper rendered as plaintext markdown with section headings and paragraph references. Useful for full-paper context in RAG or summarization.       |
| `urantia://entity/{id}` | An entity (being, place, order, race, religion, or concept) with description, aliases, related entities, and references to all paragraphs that mention it. |

### Prompts

The server also publishes two reusable prompt templates for common study workflows:

| Prompt                 | Arguments            | Description                                                                                                                         |
| ---------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `study_assistant`      | `topic` (optional)   | Primes the model to act as a Urantia Book study guide. Optionally focuses the session on a specific topic or passage.               |
| `comparative_theology` | `topic`, `tradition` | Structures a comparison between a Urantia Book teaching and another religious or philosophical tradition (e.g. Buddhism, Stoicism). |

### Example Prompts

Once connected, try asking your AI agent:

* **"Search the Urantia Book for passages about love"** — uses `search.fulltext`
* **"What does the Urantia Book say about what happens after death?"** — uses `search.semantic`
* **"Read Paper 1 about the Universal Father"** — uses the `urantia://paper/1` resource
* **"Show me paragraph 2:5.10 with surrounding context"** — uses `paragraphs.context`
* **"Find all entities of type 'place'"** — uses `entities.list`
* **"What entities are mentioned in paragraph 0:0.1?"** — uses `paragraphs.get` with `include_entities`
* **"Compare what the Urantia Book teaches about the soul with Stoic philosophy"** — uses the `comparative_theology` prompt
* **"Find Urantia Book paragraphs related to Matthew 5:3"** — uses `bible.verse.urantia_parallels`
* **"Search the Bible for passages about forgiveness and show the related Urantia teachings"** — uses `bible.search.semantic`
* **"Show me 0:0.1 with both Bible parallels and related Urantia paragraphs"** — uses `paragraphs.get` with `include_bible_parallels` and `include_urantia_parallels`

### How It Works

The MCP server uses [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http), which means:

* **No local process** — it runs on the same Cloudflare Worker as the API
* **Stateless** — each request creates a fresh server instance (no sessions to manage)
* **Same rate limits** as the REST API (100 requests/minute per IP)
* **Same data** — MCP tools query the database directly, returning the same results as the REST endpoints

### MCP vs REST

Both give you access to the same data. Choose based on your use case:

|                     | MCP (`api.urantia.dev/mcp`)      | REST (`api.urantia.dev/*`)                                      |
| ------------------- | -------------------------------- | --------------------------------------------------------------- |
| **Best for**        | AI agents (Claude, Cursor, etc.) | Apps, scripts, manual exploration                               |
| **Protocol**        | JSON-RPC over Streamable HTTP    | Standard HTTP                                                   |
| **Auth**            | None                             | None                                                            |
| **Surface**         | 19 tools, 2 resources, 2 prompts | All endpoints + `/tools/openai`, `/tools/anthropic` for SDK use |
| **Response format** | MCP content blocks               | JSON with `data`/`meta` wrappers                                |

## Docs MCP Server

Mintlify provides a hosted MCP server that lets AI agents search these documentation pages — useful for discovering endpoints, understanding usage patterns, and learning the API.

```
https://urantia.dev/mcp
```

### Setup

<Tabs>
  <Tab title="Claude Desktop">
    Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

    ```json theme={null}
    {
      "mcpServers": {
        "urantia-dev-docs": {
          "command": "npx",
          "args": ["-y", "@anthropic-ai/mcp-remote@latest", "https://urantia.dev/mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    Add to `.mcp.json` in your project root:

    ```json theme={null}
    {
      "mcpServers": {
        "urantia-dev-docs": {
          "command": "npx",
          "args": ["-y", "@anthropic-ai/mcp-remote@latest", "https://urantia.dev/mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Available Tool

| Tool               | Description                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| `SearchUrantiaDev` | Search across the documentation to find endpoint references, code examples, guides, and usage patterns. |

### Example Prompts

* **"How do I search the Urantia Papers API?"**
* **"What paragraph reference formats does the API support?"**
* **"Show me how to use the entities endpoint"**
* **"What audio voices are available?"**

## Using Both MCP Servers

For the best experience, add both servers to your client:

```json theme={null}
{
  "mcpServers": {
    "urantia-papers": {
      "url": "https://api.urantia.dev/mcp"
    },
    "urantia-dev-docs": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-remote@latest", "https://urantia.dev/mcp"]
    }
  }
}
```

* **API MCP Server** (`api.urantia.dev/mcp`) — 19 tools for accessing Urantia Book data, the World English Bible, and UB↔Bible cross-references
* **Docs MCP Server** (`urantia.dev/mcp`) — 1 tool for searching this documentation site

## Building a Custom MCP Server

If you need custom logic (e.g., combining multiple tools, caching, or preprocessing results), you can build your own MCP server that calls our REST API. See the [Build an MCP Server](/blog/mcp-server-urantia-book) tutorial for a step-by-step guide.