Mervare · Developer docs

Mervare MCP servers

Three servers, one protocol implementation, and one reason they are separate: they differ in who may call. A public harbour fact behind an OAuth flow is a fact nobody can reach, and a survey token that can queue code changes is a survey token nobody should hold. So the split is deliberate, and merging them would undo the only thing that makes them correct.

This page is rendered from lib/mcp/servers.js — the same registry the /.well-known/ documents are generated from. If a scope is listed here, a client can discover and ask for it; if it is not, it cannot.

The wide door

Every Mervare tool the caller is entitled to: surveys, observed harbour traffic, the public harbour read, the autonomous builder, and the cross-agent control plane.

Endpoint: /api/mcp
Server name: mervare
Authentication: OAuth 2.1 + PKCE, SURVEY_AGENT_TOKENS, AGENT_CONTROL_TOKENS, BUILDER_AGENT_TOKENS, or a Funding Workspace collaborator/service credential
Scopes: authorpublisheranalystreaderharbourbuilderdiscoverycontrolfunding
Writes: Surveys (scoped and audited), the builder queue, the agent control plane's hypotheses, evidence, handoffs, contacts and run log, and Funding Workspace's resources, comments, assessments, proposed actions and collaborator grants, each per entitlement.
Auth metadata: /.well-known/oauth-protected-resource
Tools: 104 survey_capabilities, survey_list, survey_get, survey_create_draft, survey_update_draft, survey_validate, survey_preview, survey_publish, survey_pause, survey_resume, survey_close, survey_clone_version, survey_send_invitation, survey_invitation_status, survey_invitation_template_validate, survey_invitation_template_save, survey_invitation_template_get, survey_invitation_template_list, survey_target_context_validate, survey_target_context_save, survey_target_context_get, survey_target_context_list, survey_invitation_create, survey_invitation_get, survey_invitation_list, survey_invitation_revoke, survey_send, survey_batch_prepare, survey_batch_execute, survey_batch_status, survey_replies, survey_reply_handled, survey_status, survey_analysis, survey_responses, survey_save_analysis, survey_artifacts, survey_audit, logbook_stats, logbook_entries, harbour_search, harbour_get, harbour_page_snapshot, harbour_query, harbour_stats, builder_list_tasks, builder_get_task, builder_queue_task, builder_cancel_task, builder_worker_status, builder_recover_worker, agent_state_overview, agent_hypothesis_list, agent_hypothesis_get, agent_hypothesis_upsert, agent_evidence_add, agent_evidence_list, agent_handoff_create, agent_handoff_list, agent_handoff_claim, agent_handoff_complete, agent_handoff_block, agent_contact_pipeline_list, agent_contact_pipeline_upsert, agent_run_record, agent_experiment_create, agent_experiment_update, agent_experiment_get, agent_experiment_list, agent_mail_prepare, agent_mail_enqueue, agent_mail_get, agent_mail_list, agent_mail_pause, agent_mail_resume, agent_event_list, agent_checkpoint_get, agent_checkpoint_set, agent_changes_since, agent_verification_record, funding_workspace_list, funding_workspace_get, funding_workspace_create, funding_resource_list, funding_resource_get, funding_resource_create, funding_resource_status_update, funding_resource_correct, funding_comment_list, funding_comment_add, funding_assessment_list, funding_assessment_add, funding_action_list, funding_action_propose, funding_action_decide, funding_collaborator_grant_list, funding_collaborator_grant_create, funding_collaborator_grant_revoke, funding_security_pause, funding_security_resume, funding_audit_list, funding_changes_since, funding_inbox, funding_inbox_ack

This endpoint filters by credential: `harbour_*` goes to every authenticated caller because it is public anyway, `survey_*` needs a survey scope and `logbook_*` the `harbour` one, `builder_*` needs the `builder` scope AND a builder grant that is re-checked on every call, and `agent_*` needs the `control` scope — or a builder credential, which reaches only its own narrow slice of the control plane (claiming and completing handoffs addressed to it), never business evidence or hypotheses. `funding_*` needs the `funding` scope — or a Funding Workspace collaborator/agent/service credential, each of which resolves to its own fixed, narrow role and never to `super_admin`. `discovery` is the floor — anyone signed in may hold it, and it reaches only the public read, so nobody leaves the consent screen empty-handed. A client is offered only what its token carries, and `serverInfo.version` fingerprints the surface that caller was served — so a cached tools/list expires when entitlement changes, not only when we deploy.

Public harbour read

Every fact a mervare.ee harbour page shows, for any caller, with no account.

Endpoint: /api/mcp/discovery
Server name: mervare-harbours
Authentication: None, by design
Scopes: none — this server takes no credential at all
Writes: None, ever.
Tools: 5 harbour_search, harbour_get, harbour_page_snapshot, harbour_query, harbour_stats

The tools project an explicit allow-list from the same composition the public page renders. If an anonymous visitor cannot get a fact from the public product, this surface must not return it.

Builder control plane

Queue a task for the autonomous builder, watch it, withdraw one it has not started.

Endpoint: /api/mcp/builder
Server name: mervare-builder
Authentication: OAuth 2.1 + PKCE (`builder` scope), or BUILDER_AGENT_TOKENS
Scopes: builder
Writes: Queues and withdraws tasks. No commit, push, approve, merge or deploy verb.
Auth metadata: /.well-known/oauth-protected-resource/api/mcp/builder
Tools: 6 builder_list_tasks, builder_get_task, builder_queue_task, builder_cancel_task, builder_worker_status, builder_recover_worker

A task that passes CI and review merges to main with no further approval. /api/mcp serves these tools too, to a caller carrying the `builder` scope; this endpoint stays so a CI job can present a builder credential and get a surface that is only the builder.

Connecting a client

Point the client at the endpoint above. Authenticated servers advertise everything else themselves: the client fetches the protected-resource document, discovers the authorization server, registers itself at /api/oauth/register and runs OAuth 2.1 with PKCE. There is no client id to paste.

Sign in as the right person. Survey and harbour scopes are super-admin only. Builder access is granted per person in /admin/users. A connection made by an account without the right is not refused — it is granted with less, and the consent screen lists exactly what remains.
Read the consent screen. It names each scope it is about to grant, and carries a warning for the two that are consequential: queueing builder work, and reading marina operational data.
Verify with survey_capabilities (or builder_capabilities). It returns the scopes actually granted. If the scope you need is missing, stop there — every call will refuse, and nothing else is worth debugging first.

A client requests the whole advertised set for a resource and cannot pick from it. That is why a connector pointed at /api/mcp asks for harbour traffic as well as surveys, and why the builder lives on its own endpoint with its own document.