MCP developer guide

Connect agents to OBS-TF MCP

How to register this Model Context Protocol server, call its tools, and pace Open Bible Stories + Theological Formation (Five Movements) content correctly.

OBS-TF MCP is a tool server — not a chat product. Clients (Claude, Cursor, BT Servant coaches, custom agents) invoke named tools over https://obs-5m-mcp.unfoldingword.workers.dev/mcp and receive structured study-manual data.

Sibling in the BT Servant ecosystem: Translation Helps MCP covers scripture helps (TN / TW / TA / TQ / passage). This server covers OBS Theological Formation manuals only.

Setup

Connect

Streamable HTTP MCP at /mcp. Same client setup as Translation Helps: Cursor uses a url; Claude Desktop uses mcp-remote. POST requires Accept: application/json, text/event-stream.

Cursor (.cursor/mcp.json)
{
  "mcpServers": {
    "obs-tf": {
      "url": "https://obs-5m-mcp.unfoldingword.workers.dev/mcp"
    }
  }
}
Claude Desktop / mcp-remote
{
  "mcpServers": {
    "obs-tf": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://obs-5m-mcp.unfoldingword.workers.dev/mcp"]
    }
  }
}
Direct HTTP (Streamable MCP)
POST https://obs-5m-mcp.unfoldingword.workers.dev/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Content domain

What the tools return

Fifty Open Bible Stories (Creation → New Creation). Each story’s manual walks observe → discuss → draft → check → serve → share (Five Movements + session parts).

Trusted source text

English from Door43 en_obs_tf (subject=OBS Theological Formation, topic=tc-ready). Indonesian from converted/local markdown until DCS-published.

Packaging resolved

Shared ![[transclusion]] templates and story-unique text look the same in tool output — clients never open TX files by hand.

Languages

Default en. Use language=id for Indonesian. Missing packs return available: false / RESOURCE_NOT_AVAILABLE (not a tool failure).

Reference

Tool map

Prefer the default during sessions. Helpers fill gaps; they should not replace paced fetches.

ToolWhen to use
list_languagesLanguages with OBS-TF content
list_resourcesAvailability for a language: available lists what exists (empty when nothing does)
list_collectionsEleven units (Creation → New Creation)
list_storiesStories 1–50 (optionally by collection)
get_frameworkFive Movements definitions + sessionFlow overview
fetch_obs_study_manualDefault. Story:frame study content + part filter
get_storyIntro + frames only
get_devotionalCommunity Study only
get_movementOne movement blob (may include drafting/checking fields)
get_study_guideFull session dump; prefer paced fetch_obs_study_manual
search_contentFind stories by keyword
get_pdfIndonesian PDF URL only — not for study Q&A

Workflow

Recommended tool loop

Discover → choose story → load the map → fetch one part at a time.

  1. Discover list_languages / list_resources — confirm OBS-TF for the language.
  2. Choose the story list_collections / list_stories — pick story 1–50.
  3. Load the map get_framework — movement definitions and sessionFlow.
  4. Fetch one slice fetch_obs_study_manual with part=… — present exact questions, then advance.
  5. Helpers as needed get_story, get_devotional, get_movement, search_content.
  6. PDF last get_pdf — only when the client needs the Indonesian file URL.
Default tool.

Prefer fetch_obs_study_manual with a specific part during live sessions. Use part: "full" sparingly — overview, not facilitation.

Primary tool

fetch_obs_study_manual

Preferred surface for BT Servant and agent sessions ((#36).

ParamDescription
referenceOBS story:frame — "1:1", "1" (whole story), "1:0" (intro). Optional obs prefix.
languageDefault en. Use id for Indonesian.
partintro | frames | community | movement1–5 | drafting | checking | conclusion | full
movementOptional 1–5 (same as part=movementN). Prefer part for drafting/checking/conclusion.
formatjson (default), md, or text — md/text render from the same parsed data.

Response includes sections, sessionFlow, and (when present) drafting, checking, conclusion.

Session flow (pace with part)

partContent returnedTypical activity
introKey idea, creedal verse, metanarrativeOrient
framesStory panel text (optionally one frame via 1:3)Read / retell
communityCommunity Study / devotionFormation practice
movement1Observation + translation-term Q&AObserve; discuss terms
movement2Discourse + theological questionsDiscuss meaning
draftingTranslation draft instructionsDraft panels
movement3Journal reflectionPersonal response
checkingTeam quality-check questionsClear / accurate / natural
movement4Ministry practice frameworkServe with the story
movement5Missional outreach frameworkShare beyond the church
conclusionClosing wrap-upHand off revised draft

Typical order from sessionFlow: intro → frames → community → movement1 → movement2 → drafting → movement3 → checking → movement4 → movement5 → conclusion.

Examples

Example tool calls

Checking questions for Indonesian story 1:

{
  "tool": "fetch_obs_study_manual",
  "arguments": {
    "reference": "1",
    "language": "id",
    "part": "checking",
    "format": "md"
  }
}

Frame-scoped observation (story 1, frame 3):

{
  "tool": "fetch_obs_study_manual",
  "arguments": {
    "reference": "1:3",
    "language": "en",
    "part": "movement1",
    "format": "json"
  }
}

Whole-story overview (use sparingly in live facilitation):

{
  "tool": "fetch_obs_study_manual",
  "arguments": {
    "reference": "7",
    "language": "en",
    "part": "full",
    "format": "json"
  }
}

Direct HTTP invoke

POST https://obs-5m-mcp.unfoldingword.workers.dev/api/tool
Content-Type: application/json

{
  "tool": "fetch_obs_study_manual",
  "arguments": {
    "reference": "1:1",
    "language": "en",
    "part": "intro",
    "format": "md"
  }
}

Add "debug": true for X-ray pipeline traces (also available on /debug).

Patterns

Agent behavior patterns

Tool call first → present exact manual text → offer to advance when the team is ready.

Pattern: One frame, one movement

Request

“Observation questions for Indonesian OBS story 2, frame 1 only.”

Agent

Calls fetch_obs_study_manual with reference: "2:1", language: "id", part: "movement1". Facilitates returned observation Q&A; does not invent replacements.

Pattern: Drafting from the manual

Request

“We finished discussing meaning. Help us draft.”

Agent

Calls part: "drafting" — not a free-form drafting prompt. Walks steps from the tool output, then suggests part: "checking".

Pattern: Missing content

Request

“Open checking for a language with no OBS-TF pack.”

Agent

Treats available: false / RESOURCE_NOT_AVAILABLE as the answer — report what is missing; do not invent checking questions.

Guardrails

Agent rules

Do not invent theology or checking criteria.

Use exact questions from the tools. Classic OBS translation notes / word links belong on Translation Helps MCP, not here.

Optional

Demo clients

These UIs call the same tools as any MCP client. They are not the product.