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

# MCP server for the Urantia Papers

> Connect Claude, Cursor, or any MCP client to the Urantia Papers. 19 tools, 2 resource templates, 2 prompts. No key needed.

The Urantia Papers API has a built-in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. An AI agent that connects to it can read and search the Urantia Papers and quote them by reference.

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

It has 19 read-only tools, 2 resource templates, and 2 prompts. It needs no key, no account, and no local process.

Not a developer? See [AI Assistants](/assistants) for steps in Claude, ChatGPT, Grok, and Gemini.

## Set up

### Claude Code

Install the plugin. It adds the server and a research skill:

```
/plugin marketplace add urantia-hub/urantia-papers-claude-code-plugin
/plugin install urantia-papers@urantia-papers
```

Or add the server only:

```
claude mcp add --transport http urantia-papers https://api.urantia.dev/mcp
```

### Cursor

Install the plugin from [cursor.directory/plugins/urantia-papers](https://cursor.directory/plugins/urantia-papers), or add the server to your MCP settings:

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

### Gemini CLI

Install the extension. It adds the server and the research skill:

```
gemini extensions install https://github.com/urantia-hub/urantia-papers-claude-code-plugin
```

### Claude, ChatGPT, Grok, and Gemini

Add the address above as a custom connector. [AI Assistants](/assistants) has the steps for each one.

### Any other client

Use the same `mcpServers` block as for Cursor. The server works with any client that supports the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).

## Where it is listed

* [MCP Registry](https://registry.modelcontextprotocol.io), as `dev.urantia/urantia-papers`
* [Smithery](https://smithery.ai/servers/urantiahub/urantia-papers)
* [Glama](https://glama.ai/mcp/connectors/dev.urantia/urantia-papers)
* [cursor.directory](https://cursor.directory/plugins/urantia-papers)

## Reference

### 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 study guide for the Urantia Papers. Optionally focuses the session on a specific topic or passage. |
| `comparative_theology` | `topic`, `tradition` | Structures a comparison between a teaching of the Urantia Papers and another religious or philosophical tradition (e.g. Buddhism, Stoicism). |

### Example Prompts

Once connected, try asking your AI agent:

* **"Search the Urantia Papers for passages about love"**: uses `search.fulltext`
* **"What do the Urantia Papers 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 Papers teach about the soul with Stoic philosophy"**: uses the `comparative_theology` prompt
* **"Find Urantia 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 (200 requests per minute for each IP address)
* **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://docs.urantia.dev/mcp
```

### Setup

Add the address to your client as a second server:

```json theme={null}
{
  "mcpServers": {
    "urantia-dev-docs": {
      "type": "http",
      "url": "https://docs.urantia.dev/mcp"
    }
  }
}
```

### 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?"**

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.