# Agent Access

ContextOwl exposes docs to agents two ways: the Model Context Protocol (MCP) endpoint and a public REST API. Both authenticate with the same agent keys and honor the same permissions.

## Create an agent key

1. Open **Admin > Settings > API**.
2. Enter a key name.
3. Choose Whole organization or a single workspace.
4. Select permissions by group, individually, or with All permissions.
5. Choose an expiry.
6. Create the key.
7. Copy the token once and store it in your secret manager.

The token starts with cowl_pat_. ContextOwl stores only a hash, so the plaintext token cannot be shown again.

## Common access profiles

| Profile | Permissions |
| --- | --- |
| Read-only assistant | search, article.read, changelog.read, workspace.read |
| Contributor (review-gated) | search, article.read, article.propose |
| Drafting assistant | search, article.read, article.create, article.update |
| Publishing assistant | Drafting permissions plus article.publish |
| OpenAPI automation | openapi.read, openapi.attach, openapi.sync, openapi.layout |

The key can never do more than the owner role allows. If the owner is restricted to assigned workspaces, the key inherits that restriction.

## What agents can do

- **Search by meaning.** The semantic_search tool ranks docs by embedding similarity (falling back to keyword search when no embeddings provider is configured), so an agent finds the right page even without exact terms.
- **Contribute under review.** With only the read-tier article.propose permission an agent submits edits as proposals; they never touch published content until an editor approves them in **Admin > Proposals**. This lets you hand an agent a broad-read key without giving it write access.
- **Browse structure as resources.** Sidebar trees, changelog, and the workspace index are readable as MCP resources, and guided prompts (onboarding an API, drafting a changelog, auditing stale docs) chain the tools for common jobs.
- **Edit landing pages.** Agents can read a workspace landing page, autofill it, and write or propose changes over MCP, the same way they work with articles.

## React to changes with webhooks

Instead of polling, subscribe an HTTPS endpoint to content events (article and changelog changes, new workspaces) in **Admin > Settings > API > Webhooks**. Each delivery is an HMAC-SHA256-signed POST (verify the X-ContextOwl-Signature header with your webhook secret), covering changes made through the app and through MCP alike. Use PING to test your receiver.

## Endpoints

MCP clients connect to the MCP endpoint on your docs host:

```text
https://{your-docs-host}/mcp
```

A versioned REST API is available under `/api/v1` using the same agent keys. See the REST API reference in the developer docs for the base URL and endpoints.

Send the token as an Authorization bearer header.

## Rate limits

MCP and API traffic is covered by a fair-use policy, and a person or a reasonable agent never hits it. If a client bursts far past fair use, ContextOwl throttles it briefly with a **429** response and a **Retry-After** header rather than metering usage or charging for it, so a well-behaved client just waits and retries.

## Developer docs

Use the developer docs for client configuration, JSON-RPC examples, resource URIs, the REST API reference, and the complete tool list:

- [MCP Quickstart](https://developer.contextowl.co/docs/platform/mcp)
- [REST API](https://developer.contextowl.co/docs/platform/rest-api)