MCP Quickstart

ContextOwl exposes your docs and docs-management workflows through MCP over Streamable HTTP. Connect any MCP client that supports remote HTTP, or call the same endpoint with plain JSON-RPC.

Use MCP when an agent needs to search docs, read Markdown, draft pages, update existing articles, manage changelog entries, sync OpenAPI references, or automate workspace setup.

Requirements

A ContextOwl account in the target organization.
An organization role that allows the action. Agent keys cannot exceed the key owner's current role.
An agent key created from Admin > Settings > API.
A client that can send HTTP requests to /mcp with an Authorization header.

1. Create an agent key

Open Admin > Settings > API and create a key.

Choose:

Key name: a readable label such as docs-agent or openapi-sync.
Workspace: choose one workspace for least privilege, or Whole organization when the agent must work across workspaces.
Permissions: pick only the tools the agent needs.
Expiry: prefer a short expiry for experiments and a rotated long-lived key for production automations.

The token starts with cowl_pat_ and is shown once. Store it in your secret manager before closing the panel.

Recommended permission sets:

Use case	Permissions
Read-only docs assistant	search, article.read, landing.read, changelog.read, workspace.read, openapi.read
Docs drafting agent	search, article.read, article.create, article.update, section.create, article.place
Publishing agent	Docs drafting permissions plus article.publish
Landing editor agent	landing.read, landing.update
Contribution-only agent	article.propose, landing.propose
Release notes agent	changelog.read, changelog.create, changelog.update, changelog.publish
OpenAPI sync agent	openapi.read, openapi.attach, openapi.sync, openapi.layout, openapi.detach
Workspace automation	workspace.read, workspace.create, workspace.update, workspace.delete

2. Connect an MCP client

Use your ContextOwl host plus /mcp. On ContextOwl Cloud this is https://contextowl.co/mcp.

{
  "mcpServers": {
    "contextowl": {
      "type": "http",
      "url": "https://contextowl.co/mcp",
      "headers": {
        "Authorization": "Bearer cowl_pat_YOUR_KEY"
      }
    }
  }
}

3. Test the endpoint

List the tools available to the key:

curl -s -X POST https://contextowl.co/mcp \
  -H "Authorization: Bearer cowl_pat_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Read one article:

curl -s -X POST https://contextowl.co/mcp \
  -H "Authorization: Bearer cowl_pat_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_article","arguments":{"workspace":"platform","slug":"mcp"}}}'

With a workspace-bound key, omit the workspace argument. With an organization-wide key, every workspace-scoped tool requires a workspace argument.

4. Give the agent an operating loop

Use this as a system or project instruction for docs agents:

You have ContextOwl MCP access.
Start with list_workspaces, then search_docs before reading or changing content.
Use get_article before update_article.
Create new pages as drafts unless explicitly asked to publish.
When changing navigation, create sections first and then place articles.
For OpenAPI docs, attach or sync the spec before moving generated pages.
Report the workspace, slug, and tool result after each write.

5. Read articles as MCP resources

ContextOwl also exposes article Markdown as resources. Resource URIs use this shape:

contextowl://{workspace}/{slug}.md

Example:

contextowl://platform/mcp.md

Resources require article.read and obey the same organization, workspace, and member-scope rules as tools. A workspace's landing page is also readable as a resource, at contextowl://{workspace}/landing.json, gated by landing.read.

Troubleshooting

Symptom	Meaning	Fix
HTTP 401	Missing, invalid, revoked, or expired key	Create a new key in Admin > Settings > API and update the client secret
permission denied	The key lacks the permission, or the owner role no longer allows it	Add the permission or use a key owned by a member with the right role
a workspace is required	The key is organization-wide and the tool needs a workspace	Pass the workspace id
this key is scoped to a single workspace	A workspace-bound key was asked to use another workspace	Omit workspace or use the bound workspace
no such workspace	The workspace is outside the key's org or member scope	Check the workspace id and member assignments
encrypted article message	The page is end-to-end encrypted	Read it in the browser; MCP never receives client-side decryption keys