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/mcp.json)
{
"mcpServers": {
"obs-tf": {
"url": "https://obs-5m-mcp.unfoldingword.workers.dev/mcp"
}
}
}
{
"mcpServers": {
"obs-tf": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://obs-5m-mcp.unfoldingword.workers.dev/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"}
- MCPhttps://obs-5m-mcp.unfoldingword.workers.dev/mcp
- Manifesthttps://obs-5m-mcp.unfoldingword.workers.dev/api/mcp-manifest
- Tool API
POST https://obs-5m-mcp.unfoldingword.workers.dev/api/tool - Healthhttps://obs-5m-mcp.unfoldingword.workers.dev/health
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).
English from Door43 en_obs_tf
(subject=OBS Theological Formation, topic=tc-ready).
Indonesian from converted/local markdown until DCS-published.
Shared ![[transclusion]] templates and story-unique text look the same
in tool output — clients never open TX files by hand.
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.
| Tool | When to use |
|---|---|
list_languages | Languages with OBS-TF content |
list_resources | Availability for a language: available lists what exists (empty when nothing does) |
list_collections | Eleven units (Creation → New Creation) |
list_stories | Stories 1–50 (optionally by collection) |
get_framework | Five Movements definitions + sessionFlow overview |
fetch_obs_study_manual | Default. Story:frame study content + part filter |
get_story | Intro + frames only |
get_devotional | Community Study only |
get_movement | One movement blob (may include drafting/checking fields) |
get_study_guide | Full session dump; prefer paced fetch_obs_study_manual |
search_content | Find stories by keyword |
get_pdf | Indonesian PDF URL only — not for study Q&A |
Workflow
Recommended tool loop
Discover → choose story → load the map → fetch one part at a time.
-
Discover
list_languages/list_resources— confirm OBS-TF for the language. -
Choose the story
list_collections/list_stories— pick story 1–50. -
Load the map
get_framework— movement definitions andsessionFlow. -
Fetch one slice
fetch_obs_study_manualwithpart=…— present exact questions, then advance. -
Helpers as needed
get_story,get_devotional,get_movement,search_content. -
PDF last
get_pdf— only when the client needs the Indonesian file URL.
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).
| Param | Description |
|---|---|
reference | OBS story:frame — "1:1", "1" (whole story), "1:0" (intro). Optional obs prefix. |
language | Default en. Use id for Indonesian. |
part | intro | frames | community | movement1–5 | drafting | checking | conclusion | full |
movement | Optional 1–5 (same as part=movementN). Prefer part for drafting/checking/conclusion. |
format | json (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)
Pace with part · advance only when the team is ready
| part | Content returned | Typical activity |
|---|---|---|
intro | Key idea, creedal verse, metanarrative | Orient |
frames | Story panel text (optionally one frame via 1:3) | Read / retell |
community | Community Study / devotion | Formation practice |
movement1 | Observation + translation-term Q&A | Observe; discuss terms |
movement2 | Discourse + theological questions | Discuss meaning |
drafting | Translation draft instructions | Draft panels |
movement3 | Journal reflection | Personal response |
checking | Team quality-check questions | Clear / accurate / natural |
movement4 | Ministry practice framework | Serve with the story |
movement5 | Missional outreach framework | Share beyond the church |
conclusion | Closing wrap-up | Hand 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
“Observation questions for Indonesian OBS story 2, frame 1 only.”
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
“We finished discussing meaning. Help us draft.”
Calls part: "drafting" — not a free-form drafting prompt.
Walks steps from the tool output, then suggests part: "checking".
Pattern: Missing content
“Open checking for a language with no OBS-TF pack.”
Treats available: false / RESOURCE_NOT_AVAILABLE as the answer —
report what is missing; do not invent checking questions.
Guardrails
Agent rules
Use exact questions from the tools. Classic OBS translation notes / word links belong on Translation Helps MCP, not here.
- Prefer
partoverfullduring a live session. - Treat
available: false/RESOURCE_NOT_AVAILABLEas a clear answer. - Default language is
en; useidwhen requested. - md/text are rendered from the same parsed JSON (never falsely empty when data exists).
- Responses may include
_meta.downstream_api_callsand_meta.cache_statusfor clients that track them.
Optional
Demo clients
These UIs call the same tools as any MCP client. They are not the product.