Connect Claude (and other MCP clients) to ARC

Status: Implemented
Configure in: Settings → Developer → Claude Connector
MCP URL (production): https://arcos.corgicy.com/mcp
Related: Public API · Outgoing webhooks · Connector internals

Tool-by-feature coverage (including Public API column) is maintained in-repo at server/src/mcp/FEATURE_STATUS.md.

MCP is the assistant integration: read + write over the same services as the web app, scoped to your account after OAuth. It is not the write-only Public API, and it does not push events to your server (use webhooks).

The in-app AI Coach uses the same permissioned tool set. You do not maintain two different views of your data.

Choose this surface when

You want…	Use
Claude / another agent to read, search, log, and decide	MCP (this page)
A watch or cron to only write water/workouts/sleep	Public API
A Brain form to notify your HTTP server	Webhooks

What you get

After you approve access, the client can (subject to tool permissions):

Read today’s ARC Day: checklist, perimeter, tasks, mood, sleep, minimum mode
Log training, cardio, water, steps, sleep, mood, meals, transactions, habits, journal
Search and write Brain notes (markdown vault with links to people, sessions, projects, …)
Create / publish / submit Brain forms (brain_form_*) — submit fires brain_form_submitted webhooks for the form owner
Query analytics (mood vs sleep, spend vs budget, training vs energy, …)
Social graph, messages, plants, wardrobe, gamification (mostly read), settings

It cannot see other users’ data. Tools run as you.

Endpoints (production)

URL	Purpose
`https://arcos.corgicy.com/mcp`	MCP JSON-RPC (this is the connector URL you paste into Claude)
`https://arcos.corgicy.com/authorize`	OAuth authorize / approve / deny
`https://arcos.corgicy.com/token`	OAuth token
`https://arcos.corgicy.com/.well-known/oauth`	OAuth discovery
`https://arcos.corgicy.com/register`	Dynamic client registration

Local: replace the host with your API origin (typically http://localhost:3001).

Enabling the connector in Settings currently requires an active subscription, same as API keys and webhooks.

Setup (Claude Desktop)

Sign in to ARC in the browser: https://arcos.corgicy.com/app.
Settings → Developer → enable Claude MCP connector. Copy the MCP server URL (https://arcos.corgicy.com/mcp).
Optionally paste the in-app system prompt, Brain prompt, and Context prompt into Claude so it uses Brain vs context_* correctly.
In Claude Desktop, add a custom MCP connector with that URL.
Complete the OAuth prompt (same browser profile that is logged into ARC).
First message: ask it to call system_get_current_datetime, then “what is on today’s perimeter?”

Other MCP clients: point them at the same /mcp URL and complete OAuth. Discovery is at /.well-known/oauth.

Rules the assistant must follow

These are product rules, not suggestions.

1. Time

Always call system_get_current_datetime before scheduling, planning, “today”, or date math. Do not infer the current date from the chat, the model’s training cutoff, or the user’s laptop clock.

The tool returns timestamp (ISO), date (YYYY-MM-DD), time, and timeZone. Timezone is server-side until per-user timezone exists.

This tool is always on (no permission toggle).

2. Knowledge vs scratch memory

Layer	Tools	Use for
Brain	`brain_`, `brain_form_`	Notes, dossiers, decisions, links to ARC records, forms
Structured ARC	`planning_`, `health_`, `training_`, `finance_`, …	Facts: weight, workouts, transactions, checklist
Context	`context_*`	Short LLM scratch: “prefer metric”, session cues. Not the vault

Do not dump Brain notes into context_write. Do not answer “what do I know about X” from Claude memory when brain_search / domain tools could apply.

Default MCP captures without a folder go to inbox/. File into projects/, people folders, etc. when the destination is clear.

3. Input layer

Log into ARC. Do not invent workouts, spends, or form answers in chat and call it done.

Permissions

Settings → Developer → Claude Connector lists domains and individual tools.

Tools with requiresPermissionToggle: false are always available: system_get_current_datetime and the core Brain set (brain_capture, brain_write, brain_read, brain_search, brain_append, folders, links, forms’ sibling vault tools, …).
Other tools are grouped by domain (health, finance, social, …). You can turn a domain or tool off.
First-time enable defaults write tools on and many list/search tools off, with Brain extras on. If Claude “can’t see” a list tool, turn that read tool on.

Missing tool in the client: refresh the connector after changing permissions; confirm the domain is enabled.

Tool catalog (by domain)

Names below are the MCP tool names (underscores). Coverage is tracked in server/src/mcp/FEATURE_STATUS.md. New product features should get tools; if something exists in the app and not here, that is a gap.

System (always on)

system_get_current_datetime

Planning / ARC Day

planning_get_today_day_summary
planning_get_today_checklist / planning_set_checklist_item_state
planning_get_today_perimeter_tasks / planning_set_perimeter_task_state
planning_get_today_mode / planning_set_minimum_mode
planning_get_week_overview
planning_get_agenda_events
sleep_get_bedtime_targets / sleep_set_bedtime_targets

Health

health_log_water_intake / health_get_water_intake_summary
health_log_steps
health_log_sleep
health_log_mood
health_log_body_metrics
Caffeine / alcohol / supplements / recreational: health_log_caffeine_intake, health_get_caffeine_summary, health_log_alcohol_intake, health_log_supplement_intake, health_get_supplement_schedule, health_list_supplements, health_log_recreational_substance_intake, health_get_alcohol_summary
Records / biomarkers: arc:health_records_*, health biomarker tools

Same writes also exist on the Public API for water, steps, sleep, mood, body metrics.

Training

training_log_workout_session, training_add_exercises_to_session, training_update_exercise_entry, training_remove_exercise_from_session, training_delete_session, training_get_recent_sessions
training_log_cardio_session
training_search_exercises, training_list_exercises, training_create_exercise
training_get_exercise_metrics
analytics_get_training_analytics

Nutrition

nutrition_get_week_meal_plan, nutrition_log_meal
nutrition_log_cooking_session, nutrition_get_cooking_frequency
nutrition_get_grocery_list, nutrition_get_recipes, nutrition_get_ingredients

Finance

finance_log_transaction, finance_get_transactions
finance_get_budget_overview, finance_set_budget_targets
finance_get_recurring_payments
finance_get_net_worth_snapshot, finance_get_net_worth_trend

Tasks & habits

tasks_create_task, tasks_update_task, tasks_log_completion
habits_get_habits, habits_log_completion, habits_get_history

Journal, reading, meditation

journal_log_entry, journal_get_recent_entries, journal_get_entries_by_range
journal_free_create / journal_free_update / journal_free_get / journal_free_list / journal_free_search
reading_log_session, reading_get_history, reading_get_library
meditation_log_session, meditation_get_history

social_get_connections, social_get_social_graph
social_log_interaction, social_get_interaction_history
social_get_groups, social_get_group_highscores
social_get_happenings, social_log_happening
messaging_get_recent_conversations, messaging_get_unread_count, messaging_send_message

Plants, wardrobe, home, inventory

plants_get_plants, plants_log_watering, plants_get_overdue
wardrobe_get_items, wardrobe_log_outfit, wardrobe_get_outfit_history
house_* (rooms, furniture, maintenance, cleaning, home projects)
inventory_*, fragrance / jewelry / cellar / spirits / pantry / garden / vehicles / pets / media / culture / outdoor / trips

Gamification (mostly read)

gamification_get_character, gamification_get_achievements, gamification_get_streaks
gamification_get_house_state, gamification_get_room_layout
gamification_get_collections, gamification_get_banking_state
Additional arc:gamification_* battle/shop/skill tools

Analytics

analytics_get_mood_vs_sleep_correlation
analytics_get_training_vs_energy_trend, analytics_get_training_vs_sleep_correlation
analytics_get_spend_vs_budget_trend
analytics_get_habit_completion_rate
analytics_get_social_activity_trend
analytics_get_net_worth_over_time
analytics_get_weight_trend
Plus metric/correlation/insights helpers (analytics_get_metric, analytics_list_metrics, …)

Notifications & settings

notifications_get_center, notifications_get_unread_count, notifications_get_reminders
settings_get_preferences, settings_set_preferences, settings_get_subscription_status

Context (LLM scratch — not Brain)

context_write, context_read, context_list, context_search, context_delete_key, context_rename_key
context_history, context_get_for_entity
context_set_reminder, context_list_reminders, context_complete_reminder

Brain (vault)

Core (always on): brain_capture, brain_write, brain_append, brain_read, brain_search, brain_resolve, brain_backlinks, brain_daily, brain_folder_list, brain_folder_create, brain_move, brain_link, brain_unlink, brain_outline, brain_organize, brain_neighborhood, brain_history, brain_entity_types, brain_notes_about, brain_publish, plus merge/split/include/conflict tools.

Extended: brain_query, brain_view_*, brain_export, brain_ingest, brain_stats, brain_graph_global, brain_templates, brain_task_sync, brain_attach_*, brain_properties_*, brain_filing_rules_*, …

Brain forms (MCP)

Tool	Role
`brain_form_list`	Your forms
`brain_form_get`	Editor payload
`brain_form_make` / `brain_form_create`	Create bound to a database
`brain_form_update`	Patch config / questions
`brain_form_publish`	Public slug `/brain/f/<slug>`
`brain_form_submit`	Submit answers → database record → `brain_form_submitted` webhook. HTTP equivalent: `POST /api/v1/brain/forms/:id/submit`
`brain_form_delete`	Delete

Public respondents still use the published URL. MCP submit is the authenticated/owner path. Both hit the same service.

Other domains

Coach, ISO audit, learning, life skills, self-care, social reps, articles, travel, dreams, emotions, wishlist, entity dedupe, databases / synced blocks / batch / interface tools — all exposed as MCP tools when enabled. Ask the connector to list tools, or inspect Settings.

Some tools are registered twice (name and arc:name) for client compatibility. Prefer the documented name; both call the same service.

Brain forms + webhooks

brain_form_submit (MCP) and the public form POST both create a database record, then fire brain_form_submitted for the form owner.

To push answers to your own HTTP API: subscribe a webhook, then handle it on your server. Guide: Outgoing webhooks.

Public API vs MCP vs session API

	MCP	Public API	`/api/v1/*` session
Auth	OAuth (MCP client)	`Authorization: Bearer arc_…`	httpOnly cookie
Read	Yes	Almost no (`GET /exercises/search` only)	Yes (the web app)
Write	Broad	Water, workouts, steps, meditation, cardio, mood, sleep, body metrics	Broad
Brain / forms	Yes	No	Yes
Who it’s for	Assistants	Devices / scripts	The ARC web UI

In-app prompts

Settings → Developer includes copy-paste prompts:

System prompt — ARC as source of truth; call tools; Brain over Claude memory
Brain prompt — when to brain_capture / brain_search
Context prompt — keep context_* small

Paste them into Claude’s custom instructions / project knowledge so the model does not skip tools.

Recent MCP activity (tool names, timestamps) also appears on that page for debugging.

Troubleshooting

Symptom	What to check
OAuth loop	Logged into ARC in the same browser profile that opens `/authorize`
Connector disabled / upgrade CTA	Active subscription
Empty “today”	Assistant skipped `system_get_current_datetime` or used a guessed date
Missing tool	Settings → Developer → domain/tool toggle; reconnect the client
Writes succeed, lists fail	Read/list tools default off for some domains — enable them
Brain vs Context confusion	Knowledge → `brain_`. Scratch → `context_`
Form submit, no webhook	Subscribe to `brain_form_submitted` and handle it on your server
Local MCP	API must be reachable from the MCP client; URL is your server `/mcp`, not the Vite port

Choose this surface when​

What you get​

Endpoints (production)​

Setup (Claude Desktop)​

Rules the assistant must follow​

1. Time​

2. Knowledge vs scratch memory​

3. Input layer​

Permissions​

Tool catalog (by domain)​

System (always on)​

Planning / ARC Day​

Health​

Training​

Nutrition​

Finance​

Tasks & habits​

Journal, reading, meditation​

Social & messaging​

Plants, wardrobe, home, inventory​

Gamification (mostly read)​

Analytics​

Notifications & settings​

Context (LLM scratch — not Brain)​

Brain (vault)​

Brain forms (MCP)​

Other domains​

Brain forms + webhooks​

Public API vs MCP vs session API​

In-app prompts​

Troubleshooting​