---
title: Cedros Agent Integration Guide
audience: AI agents and automated systems
---

# Cedros Agent Integration Guide

Cedros exposes one site's reviewed operating surface through MCP. Use MCP for normal site administration; use the lower-level HTTP API only when building a direct integration that cannot use MCP.

## Entry Points

| Path | Use |
|------|-----|
| `/connect.md` | Start here to configure this site's MCP connection for the current client |
| `/skill.md` | Start here: capability landscape, operating rules, and published skills |
| `/skills/admin-site-operator.md` | Canonical site-operation skill |
| `/page-docs/index.json` | Compact index of page-guide sections |
| `/page-docs/sections/{sectionKey}.json` | Page metadata for one section |
| `/page-docs/{slug}.md` | One exact page guide, loaded only when needed |
| `/mcp` | Authenticated MCP server endpoint |
| `/.well-known/mcp-lite.json` | Compact unauthenticated tool orientation |
| `/.well-known/mcp` | Full unauthenticated tool schemas |
| `/skill.json` | Machine-readable skills and extension capabilities |
| `/.well-known/ai-discovery.json` | Machine-readable index of all discovery surfaces |
| `/openapi.json` | Lower-level HTTP API specification |

Discovery documents remain public when the website is gated. That does not grant access to MCP or protected APIs.

## Connect and Discover

1. Read `/connect.md` and follow the matching client section. Use a personal MCP API key created in **Assistant Settings → MCP** for site operations, or a task connection token for task-only coordination. Send either as an `Authorization: Bearer` credential.
2. Let the client complete MCP initialization.
3. Inspect `resources/list`.
4. Branch on the returned resources. Personal API-key sessions should start at `cedros://admin/areas`, choose one area, then read one section for exact schemas. Task-token sessions expose `cedros://tasks`, `cedros://tasks/current`, and `cedros://agents` and reject admin-resource reads.

Runtime discovery is authoritative. Available tools vary by Cedros version, enabled features and extensions, authenticated permissions, and token scope. Never invent a tool name, input field, confirmation token, or permission.

## Capability Map

`cedros://admin/areas` is the live capability map. Its six area summaries contain no schemas and link to focused section resources, which provide the narrowest full-schema view. Standard MCP clients may still materialize the broader permission-filtered `tools/list`. Matching `/skills/cedros-*.md` guides provide concise workflows without copying those contracts.

For questions about what is on a specific admin page or how its UI workflow behaves, read `cedros://admin/page-docs`, choose one `cedros://admin/page-docs/sections/{sectionKey}` summary, and then read one `cedros://admin/page-docs/{slug}` resource. Do not load every section or page guide.

## Operating Contract

1. Identify the surface, intent, and exact target.
2. Read current state with the dedicated namespace before writing.
3. Prefer a page-specific tool over generic runtime-content or collection tools.
4. Keep reversible content edits in draft mode unless publication is explicit.
5. Require the exact schema-defined confirmation for publish, send, archive, delete, restore, migration commit, managed-domain action, or extension capability execution.
6. Return the tool name, target, resulting state, and any permission or confirmation blocker.

## Authentication and Scope

Send credentials only through the MCP client's authentication configuration:

```text
Authorization: Bearer <token>
```

A personal MCP API key inherits the permissions held by its issuer when it is created. A task connection token can operate only task-board tools. `x-cedros-org-id` is optional delegated organization context, not an authentication method, and it does not select another site.

Never request or pass private keys, payment details, provider credentials, connection strings, transfer authorization codes, external-DNS tokens, or unnecessary personal data through tools. Credential-bearing flows stay in their signed-in UI unless an explicit reviewed tool contract says otherwise.

## Direct HTTP Integrations

Use `/openapi.json` for core HTTP contracts and manifest-published extension capability metadata from `/skill.json` for reviewed extension execution. Protected writes still require authentication and server-side authorization. Do not derive HTTP endpoints from MCP tool names.