--- title: MCP Agent Authoring description: >- Build and run Clear Ideas Agents from compatible MCP clients such as Codex, Claude, or Cursor while keeping context governed. ogTitle: MCP Agent Authoring ogDescription: >- Learn how compatible MCP clients can create, edit, and run Clear Ideas Agents through governed Clear Ideas tools. ogImage: /assets/images/og/agents-mcp-agent-authoring.webp navigation: icon: fasl fa-code-branch --- # MCP Agent Authoring Compatible MCP clients can help create, edit, validate, and run Clear Ideas Agents while keeping source context and execution governed by Clear Ideas. Use MCP authoring when you want an external AI client to assist with Agent design, testing, or iteration without turning approved Clear Ideas content into unmanaged prompting. The recommended setup is to install the Clear Ideas marketplace for your MCP client. The marketplace packages the Clear Ideas MCP server, OAuth configuration, and agent authoring guidance so the client can work against the current Clear Ideas schema and runtime. ## Typical Uses MCP authoring can help with: - drafting a new Agent definition from a natural language request - refining Agent prompts and variables - validating source connection requirements - creating or updating schedules - testing an Agent with sample variables - documenting the Agent's purpose and expected outputs ## Install in Codex Use the Clear Ideas Codex marketplace when you want to author Agents from Codex. Requirements: - a Clear Ideas account - Codex with plugin support - browser access to complete the Clear Ideas OAuth flow Add the marketplace: ```bash codex plugin marketplace add clearideas/codex ``` Open the Codex plugin directory: ```text /plugins ``` Select the `clearideas` marketplace and install **Clear Ideas**. After installation, start a new Codex thread and authenticate the `clearideas` MCP server when Codex prompts for authorization. The marketplace repository is [clearideas/codex](https://github.com/clearideas/codex). It installs the `clearideas-codex` plugin, which includes Clear Ideas MCP tools, OAuth authentication, governed knowledge search, cited answers, and Agent authoring guidance. After authentication, Codex can use Clear Ideas tools for: - governed knowledge search and cited answers - Site and content metadata - file content retrieval and diffs - authorized file and folder writes - Agent listing, authoring, validation, execution, run inspection, and scheduling When asking Codex to author an Agent, describe the business outcome, approved Sites or connections, expected variables, run cadence, and any review requirements. Codex should use Clear Ideas validation before saving or updating the Agent. ## Install in Claude Code Use the Clear Ideas Claude Code marketplace when you want to author Agents from Claude Code. Requirements: - a Clear Ideas account - Claude Code with plugin support - browser access to complete the Clear Ideas OAuth flow Add the marketplace: ```bash claude plugin marketplace add clearideas/claude ``` Install the plugin: ```bash claude plugin install clearideas-claude ``` Restart Claude Code or reload plugins: ```text /reload-plugins ``` Authenticate the Clear Ideas MCP server: ```text /mcp ``` Select `clearideas` and complete the OAuth flow. The marketplace repository is [clearideas/claude](https://github.com/clearideas/claude). It installs the `clearideas-claude` plugin, which includes Clear Ideas MCP tools, OAuth authentication, governed knowledge search, cited answers, and Agent authoring guidance. After authentication, Claude Code can use Clear Ideas tools for the same governed authoring workflow: source discovery, Agent drafting, validation, execution, run inspection, and scheduling. ## MCP Endpoint Both marketplaces configure the Clear Ideas MCP endpoint: ```text https://api.clearideas.com/mcp ``` Authentication uses Clear Ideas OAuth through MCP discovery. The client should open a browser-based consent flow, then return to Codex or Claude Code with the authenticated `clearideas` server available. Do not paste Clear Ideas passwords or OAuth tokens into prompts. Use the client authentication flow provided by the plugin and MCP server. ## Governance Model MCP access should be scoped. The client should only receive permitted Clear Ideas context and only use tools allowed by the access key, connection, or policy. Content reads and cited answers can become governed evidence when configured. Discovery operations, such as listing available Sites or folders, are usually better understood as audit trail events with MCP correlation metadata. ## Recommended Workflow 1. Define the Agent's business purpose. 2. Identify approved Sites and source connections. 3. Draft the Agent definition with the MCP client. 4. Review variables, prompts, tools, model choices, and evidence settings. 5. Create or update the Agent in Clear Ideas. 6. Run a test with safe variables. 7. Review output and evidence. 8. Schedule or publish only after review. ## Authoring Prompts Good MCP authoring prompts tell the client what to build and what governance boundaries to preserve. Include: - the Agent's purpose and audience - approved Clear Ideas Sites, folders, or Agent Connections - required input variables and safe sample values - expected output format - whether the Agent may write files, call webhooks, or update external systems - citation or evidence requirements - schedule, trigger, or webhook requirements - review and approval expectations Example: ```text Create a Clear Ideas Agent that prepares a weekly customer escalation summary. Use only the Customer Support Site and the approved Salesforce read-only connection. The Agent should accept startDate and endDate variables, produce a concise executive summary, cite supporting source records, and validate the definition before saving. Do not enable write tools. ``` ## Validation and Review Treat Clear Ideas as the source of truth for Agent schema, validation, persistence, and runtime behavior. The MCP client should read the current schema or saved Agent definition when details matter, then validate before creating or updating an Agent. Before publishing, review: - selected model and fallback behavior - prompts and variables - source connections and allowed tools - read/write mode - evidence settings - schedules, triggers, and webhook payload mappings - test run output and run evidence If validation returns blocking issues, fix those issues instead of saving a partial definition. ## Related Documentation - [Model Context Protocol](/ai/model-context-protocol) - [Agent Connections](/agents/connections) - [Source Connections and Tool Policy](/agents/source-connections-and-tool-policy) - [Controlled Tools and Egress](/agents/controlled-tools-and-egress)