# Copal

> Copal is a hosted, agent-native Obsidian-compatible vault. It exposes your markdown notes as a
> remote MCP server plus a REST API, with server-side semantic (vector) search - so an AI agent can
> read, write, search and organise your notes, and you can sync the same vault to Obsidian on your
> desktop. Your notes stay plain-text markdown you own and can export at any time.

Copal works with Obsidian but is NOT affiliated with, or endorsed by, Obsidian.md or Dynalist Inc.

Homepage: https://copal.uk
Pricing: Solo $4/mo or $3/mo billed annually (2 GB, 2,000 agent calls/day); Pro $9/mo or $7/mo billed annually (12 GB, 5,000 calls/day). No free tier. See "Plans & limits" below.

## Connect (for AI agents)

MCP endpoint (Streamable HTTP): https://api.copal.uk/mcp

The endpoint is an OAuth 2.1 protected resource. To connect, follow the standard remote-MCP flow -
most MCP clients (e.g. Claude) do this automatically when you give them the URL above:

1. GET https://api.copal.uk/mcp with no token → 401 with a WWW-Authenticate pointing at discovery.
2. Discover the auth server:
   - https://api.copal.uk/.well-known/oauth-protected-resource
   - https://api.copal.uk/.well-known/oauth-authorization-server (RFC 8414)
3. Register a client dynamically (RFC 7591): POST https://api.copal.uk/register
4. Start authorization with PKCE (S256): GET https://api.copal.uk/authorize?...
   - Copal shows a sign-in page and emails a passwordless magic link. Opening the link signs you in
     and, if you have an active subscription, completes the authorization.
5. If you have no active subscription, the connect flow returns HTTP 402. Subscribe first:
   POST https://auth.copal.uk/api/auth/subscription/upgrade
   body: {"plan":"solo"|"pro","annual":true|false,"successUrl":"https://copal.uk/?welcome=1","cancelUrl":"https://copal.uk/"}
   → returns a Stripe Checkout URL. After payment, retry the authorization.
6. Exchange the code for an access token: POST https://api.copal.uk/token
7. Call the MCP endpoint with `Authorization: Bearer <access_token>`.

Scopes: `vault.read`, `vault.write` - grant only what you need (a read-only grant never exposes the
write tools).

## MCP tools

Read (need vault.read):
- obsidian_get_note - read a note by path
- obsidian_list_notes - list notes (optional prefix)
- obsidian_search_notes - search; mode = keyword | semantic | hybrid
- obsidian_list_tags - all tags with counts
- obsidian_get_backlinks - notes linking to a note

Write (need vault.write):
- obsidian_write_note - create/overwrite a note
- obsidian_append_to_note - append content
- obsidian_patch_note - patch a note
- obsidian_delete_note - delete a note
- obsidian_manage_frontmatter - read/update YAML frontmatter
- obsidian_manage_tags - add/remove tags
Reads return a `version`; write/append/patch tools accept an optional `base_version` for safe
concurrent edits (see "Safe writes" below).

Vault tokens (a signed-in, write-scoped grant - for Obsidian desktop sync):
- copal_create_vault_token - mint a durable WebDAV credential (cvt_live_…) bound to your vault
- copal_list_vault_tokens - list your vault tokens
- copal_revoke_vault_token - revoke one

## REST API

Base: https://api.copal.uk (same OAuth access token as MCP)
- GET    /vault?prefix=&limit=            list notes
- GET    /vault/{path}                    read a note (response carries ETag = the note's version)
- PUT    /vault/{path}   {"content": …}   write a note; send If-Match: "<etag>" for a safe write (412 if stale)
- DELETE /vault/{path}                    delete a note
- GET    /search?q=&mode=keyword|semantic|hybrid   search
- GET    /tags                            tags with counts
- GET    /backlinks/{path}                backlinks
- GET    /account/export                  download the whole vault as a .zip
OpenAPI: https://api.copal.uk/openapi.json   Swagger UI: https://api.copal.uk/docs

## Safe writes (avoid clobbering)

Every note has a `version` (its ETag). Reads expose it — MCP tools return `version`; REST/WebDAV GET
returns an `ETag` header. To edit safely, read first, then pass the version back on the write:
- MCP write/append/patch tools: `base_version`
- REST/WebDAV PUT: `If-Match: "<etag>"`
If the note changed since you read it, the write fails (MCP: an error; REST/WebDAV: HTTP 412) instead of
overwriting — re-read, merge, and retry. Writes with no version are unconditional (last-writer-wins), so
prefer read-before-write whenever a human or another agent might be editing the same note.

## Plans & limits

Per-plan caps (enforced): Solo = 2 GB vault storage + 2,000 agent calls/day; Pro = 12 GB + 5,000
calls/day. A "call" is one MCP or REST request (a batched `/mcp` request counts as one). When the daily
quota is spent, further calls return HTTP 429 with a `Retry-After` header and a `resetsAt` (next UTC
midnight). A write that would exceed the storage cap returns HTTP 413 (MCP: an error result); reads,
search, and existing-note sync are never blocked. Human Obsidian sync over WebDAV is exempt from the daily
call quota. Semantic search is included on BOTH plans. Support: email support@copal.uk — Pro gets a
first response within one business day.

## Obsidian desktop sync (for humans)

Copal speaks WebDAV at https://api.copal.uk/dav/. Ask your connected agent to run
`copal_create_vault_token`, then in Obsidian's Remotely Save plugin choose WebDAV, set the address to
https://api.copal.uk/dav/ and paste the `cvt_live_…` token as the password (any username). The vault
your agent sees and the vault you edit in Obsidian are the same vault.

## Search by meaning

`mode=semantic` (or `hybrid`) uses a server-side vector index - no local indexing, no plugins - so an
agent can find notes by meaning, not just matching words.