# HTTP API

No MCP client is required. The /mcp endpoint accepts stateless JSON-RPC over HTTP, using the same bearer agent key as MCP clients.

## Endpoint

```http
POST /mcp
Authorization: Bearer cowl_pat_YOUR_KEY
Content-Type: application/json
Accept: application/json, text/event-stream
```

Use your ContextOwl host. For hosted developer docs, the full endpoint is:

```text
https://developers.contextowl.co/mcp
```

For local development through Vite, use:

```text
http://developers.localhost:5173/mcp
```

## Request shape

Tool calls use method=tools/call and pass the tool name plus arguments:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_article",
    "arguments": {
      "workspace": "platform",
      "slug": "mcp"
    }
  }
}
```

## List tools

```bash: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"}'
```

## Search docs

```bash:search.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":"search_docs","arguments":{"workspace":"platform","query":"agent keys"}}}'
```

## Read an 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":3,"method":"tools/call","params":{"name":"get_article","arguments":{"workspace":"platform","slug":"mcp"}}}'
```

## Create a draft article

```bash:create-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":4,"method":"tools/call","params":{"name":"create_article","arguments":{"workspace":"platform","title":"Agent Draft","section":"Guides","markdown":"# Agent Draft\n\nDrafted over MCP."}}}'
```

## Publish an article

Publishing is a status change, so the key needs article.update and article.publish.

```bash:publish.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":5,"method":"tools/call","params":{"name":"update_article","arguments":{"workspace":"platform","slug":"agent-draft","status":"STABLE"}}}'
```

## Read a resource

Article Markdown can be read as a resource URI.

```bash:resource.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":6,"method":"resources/read","params":{"uri":"contextowl://platform/mcp.md"}}'
```

## Error handling

Transport failures use HTTP status codes. Tool-level failures are returned as normal MCP tool errors in a 200 response. Handle both.

Common tool errors:

- permission denied: the key lacks the required permission or role ceiling.
- a workspace is required for this org-wide key: pass workspace in arguments.
- this key is scoped to a single workspace: omit workspace or use the bound workspace.
- no such workspace: the workspace id is invalid, cross-org, or outside member scope.