Connect Shafeh to Muse, Instinct and agent workspaces

Install the Shafeh connector

Includes a Python client and CLI, a TypeScript client, a local stdio bridge, configuration and a workspace skill. Your workspace must register the tools or enable the command runner. OAuth connects your account; it does not install tools.

Download connector package Read-only configuration Configuration with writes

The configuration contains no credentials. Keep tokens in your workspace's secret store.

Connecting an account does not automatically expose tools in Muse. The workspace must support MCP tool registration, or install the Shafeh client and skill from the downloadable package below.
Start with the read-only server https://shafeh.org/mcp/read-only. For writes, use https://shafeh.org/mcp and grant only the scopes you need. Split learning_read/learning_write, family_read/family_write and memorials_read/memorials_write tools support separate host permissions.
Download the package below, unpack it, and run python3 shafeh_client.py list-tools to verify public access. Import SKILL.md into the workspace and configure its command runner or stdio MCP support explicitly.
For account access, create a personal access token at https://shafeh.org/settings/connections, store it as SHAFEH_ACCESS_TOKEN in the workspace's secret store, then run python3 shafeh_client.py doctor. The package also includes a PKCE OAuth flow that bypasses the connector card.
If the OAuth card reports an error before Shafeh sign-in, run a fresh connection attempt; save the step and request ID if Shafeh supplies them. A reused capture link may be stale. A PAT is the fallback, not proof that the card's OAuth path works.
If it can only make HTTP calls, use the REST API (https://shafeh.org/api/v1/agent/openapi.json) with a personal access token. The package explains the SDK and CLI equivalents.
Access tokens last an hour and refresh tokens rotate: a workspace that stores credentials must save the new refresh token each time.

What your assistant can do

Contract version 2026-10-25.1. Tools marked sign-in need a connected account.

Tool	What it does
today	Today's Jewish date, parsha, holidays and the day's learning (Chumash with Rashi, Tehillim, Tanya, Rambam, Hayom Yom), with full Hebrew text, plus zmanim for a place. Examples: "what's today?", "today's Tanya", "tonight's Rambam 1 perek", "zmanim in Los Angeles tomorrow".
texts	Open any text in Shafeh's library by reference: Tanach (with Rashi), Tehillim, Mishnah, Talmud Bavli, Shulchan Aruch / Mishnah Berurah / Kitzur, the siddur, and haftaros. Examples: "Berachos 2a", "Mishnah Avos 1", "Tehillim 23", "OC 1:1", "Mishnah Berurah 25", "mincha".
calendar	Convert dates between the Hebrew and civil calendars, see a month, find multi-day periods (the Three Weeks, the Omer…), and work out a Hebrew birthday or personal Tehillim kapitel from a birth date. Examples: "15 Shevat 5787", "Hebrew date of 2019-03-10", "kapitel for someone born 2010-05-02 after sunset".
learning	Your learning history, bookmarks (continue where you left off) and preferences. Requires sign-in. Sign-in: me, preferences, update_preferences, history, mark_learned, unmark_learned, bookmarks, set_bookmark, continue
family	Your family's Hebrew names and birthdays: everyone's Tehillim kapitel today, upcoming Hebrew birthdays, and names for tefillah. Requires sign-in. Sign-in: list, kapitels_today, upcoming_birthdays, tefillah_names, add_or_update_member, remove_member
memorials	Mishnayos memorials: see progress, claim perakim and check off mishnayos. Viewing is open; claiming requires sign-in. Sign-in: mine, claim_perek, claim_many, check_off_mishnah, release_claim, create_memorial

Skills

Short guides that teach an assistant to use Shafeh well (quote Hebrew verbatim, keep attributions, ask instead of guessing). Upload a zip in Claude, install by URL elsewhere.

daily-learning — SKILL.md · zip
family-tehillim — SKILL.md · zip
halacha-lookup — SKILL.md · zip
learn-in-memory — SKILL.md · zip
shafeh — SKILL.md · zip
zmanim-and-calendar — SKILL.md · zip

Accounts and privacy

Nothing is needed for daily learning, the library or the calendar.
Connecting asks you to sign in with an email code (a free account is created if you don't have one) and shows exactly what the assistant may do. Family names and birthdays are a separate permission.
Anything others will see (claiming several perakim, starting a memorial) or that deletes something is shown to you as a preview first; the assistant can't approve it for you.
See and disconnect every assistant, and manage personal tokens, at Settings → Connections.

For developers

MCP: https://shafeh.org/mcp (stateless Streamable HTTP). Sign-in-required alias: https://shafeh.org/mcp/account.
OAuth metadata: https://shafeh.org/.well-known/oauth-protected-resource/mcp, https://shafeh.org/.well-known/oauth-authorization-server. PKCE S256; dynamic registration or client metadata documents; resource-bound tokens; 1-hour access tokens, rotating refresh tokens.
REST twin: https://shafeh.org/api/v1/agent/openapi.json · catalog: https://shafeh.org/api/v1/agent/catalog
Headers: Authorization: Bearer <token>, X-Agent-Name, Idempotency-Key for writes.
Diagnostic: shafeh-mcp-check.py (standard library, read-only; --account also checks the connected account).
Read-only MCP: https://shafeh.org/mcp/read-only. The learning_read, family_read and memorials_read tools cannot write; their _write counterparts are separate tools at /mcp.

Worked OAuth example

curl -X POST https://shafeh.org/oauth/register -H 'Content-Type: application/json' \
  -d '{"client_name":"My agent","redirect_uris":["http://127.0.0.1:8765/callback"],"scope":"account:read learning:read learning:write"}'

# open in a browser (start the loopback listener first):
https://shafeh.org/oauth/authorize?client_id=<client_id>&redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback
  &response_type=code&state=<random>&code_challenge=<base64url(sha256(verifier))>&code_challenge_method=S256
  &resource=https%3A%2F%2Fshafeh.org%2Fmcp

# check state, then:
curl -X POST https://shafeh.org/oauth/token -d grant_type=authorization_code -d client_id=<client_id> \
  -d code=<code> -d redirect_uri=http://127.0.0.1:8765/callback -d code_verifier=<verifier> -d resource=https://shafeh.org/mcp

Troubleshooting

Tool names (today, texts…) are called with tools/call — they aren't JSON-RPC methods.
Read structuredContent first. An empty list is an answer; errors set isError and carry an error code.
401 invalid_token: the access token expired or was revoked — refresh it (and store the new refresh token) or reconnect.
403 insufficient_scope: reconnect and approve the scope named in WWW-Authenticate.
Can't call tools at all? Every result has a source_url on shafeh.org to open instead.