Documentation

MCP Agent Authoring

View as Markdown

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:

codex plugin marketplace add clearideas/codex

Open the Codex plugin directory:

/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. 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:

claude plugin marketplace add clearideas/claude

Install the plugin:

claude plugin install clearideas-claude

Restart Claude Code or reload plugins:

/reload-plugins

Authenticate the Clear Ideas MCP server:

/mcp

Select clearideas and complete the OAuth flow. The marketplace repository is 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:

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.

  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:

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.