Overview

What the server does

Quilvo exposes a focused MCP server for personal AI assistants and local automation. It is intentionally smaller than the JSON API: assistants can discover project context, inspect session history, and log a writing session when the user asks them to.

Endpointhttps://quilvo.app/mcp/quilvo

TransportHTTP MCP

AuthenticationBearer token

Token modelScoped API key

Authentication

Use scoped bearer tokens

Quilvo MCP uses the same public API keys as the JSON API. Users create keys from Settings / API Keys, choose explicit abilities, and pass the key in the Authorization header.

Authorization: Bearer YOUR_API_KEY
Accept: application/json

OAuth: MCP clients generally prefer OAuth for broad third-party authorization. Quilvo starts with Sanctum-style bearer tokens because the app already has user-managed scoped keys. OAuth can be added later for clients that require it.

Abilities

Ability	Description
`projects:read`	Read projectsList projects and read project details.
`projects:write`	Write projectsCreate projects and update project metadata.
`sessions:read`	Read sessionsList writing sessions and read today's session summary.
`sessions:write`	Write sessionsCreate single or bulk writing sessions.

Tools

Available tools

Tool visibility follows the token abilities. A key with only projects:read will not show the session write tool to the assistant.

Tool	Ability	Writes	Purpose
`list-projects`	`projects:read`	No	List the user projects with status, type, target, current count, and progress.
`get-project`	`projects:read`	No	Read one project. Recent sessions are included when the key can read sessions.
`list-writing-sessions`	`sessions:read`	No	List recent writing sessions and return totals for the selected range.
`log-writing-session`	`sessions:write`	Yes	Create a writing session and update the project current count.

Connect

Client setup

MCP client configuration differs by host, but the required pieces are the same: the server URL and an authorization header. Use HTTPS in production.

01
Create a key
Generate a public API key from Settings / API Keys with the smallest abilities the assistant needs.
02
Add the MCP server
Use the remote HTTP endpoint and send the key as an Authorization bearer token.
03
Let tools stay narrow
Read-only keys only advertise read tools. Add sessions:write only when the assistant should log progress.

Connection values

{
  "url": "https://quilvo.app/mcp/quilvo",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}

Some local MCP clients use Node's certificate store. If a local development URL fails over HTTPS, use the local HTTP URL while developing.

Examples

Tool arguments

list-projects

Find active drafting projects.

{
  "status": "drafting",
  "include_archived": false,
  "limit": 10
}

log-writing-session

Add 750 words to a project and keep the session history intact.

{
  "project_id": "9b7d4f6a-...",
  "word_count_action": "add",
  "word_count": 750,
  "date": "2026-05-24",
  "duration_minutes": 45,
  "notes": "Morning session."
}

log-writing-session

Set the project total when an editor or writing app knows the latest count. Quilvo stores only the calculated session delta.

{
  "project_id": "9b7d4f6a-...",
  "word_count_action": "set_total",
  "word_count": 42100
}

MCP or API

Use the right surface

Use MCP when an AI assistant needs a small, discoverable tool surface. Use the JSON API when you are building an app, script, importer, or integration that controls its own interface and request flow.