# 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, 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 |
| 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. For the hosted developer docs this is https://developers.contextowl.co/mcp.

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

For local development through Vite, use http://developers.localhost:5173/mcp. The Vite dev server proxies /mcp to the Go backend.

## 3. Test the endpoint

List the tools available to the key:

```bash:list-tools.sh
curl -s -X POST https://developers.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:

```bash:get-article.sh
curl -s -X POST https://developers.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:

```text:agent-instructions.txt
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:

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

Example:

```text
contextowl://platform/mcp.md
```

Resources require article.read and obey the same organization, workspace, and member-scope rules as tools.

## Troubleshooting

| Symptom | Meaning | Fix |
| --- | --- | --- |
| HTTP 401 | Missing, invalid, revoked, or expired key | Create a new key in 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 |