Skip to main contentSkip to footer
For agents

MCP setup

Connect your agent runtime to the public Blueprint MCP endpoint in three steps.

View all public tools

The endpoint

The public MCP endpoint is https://aidesignblueprint.com/mcp. It uses JSON-RPC 2.0 over HTTP with stateful sessions (initialize → tools/call → DELETE). The protocol version is 2025-11-25. No API key is required for anonymous read-only tools.

Proof calls

Run clusters.list() first to confirm the session and see the top-level doctrine categories. Then run examples.search(query="orchestration visibility steering", limit=3) to validate search. Both calls should complete in under two seconds on the first session.

Tool selection guidance

Use principles.get(slug) or examples.get(slug) when you know what you need, these are faster and cheaper than bulk listing. Use principles.search or examples.search when the slug is unknown. Use clusters.list() only for discovery or to surface the full doctrine map. Avoid principles.list() on every call, it returns all principles and adds tokens your model must process.

Public MCP endpoint

https://aidesignblueprint.com/mcp

Use this same endpoint for Claude, Codex, Cursor, Gemini CLI, and curl-based QA. Windsurf, GitHub Copilot, and other file-driven clients primarily use the static artifacts above, with MCP as an optional extension.

Shared config

{
  "aidesignblueprint": {
    "type": "http",
    "url": "https://aidesignblueprint.com/mcp"
  }
}

Compatibility and session

The transport is Streamable HTTP. Compatible clients run `initialize`, receive `mcp-session-id`, send `notifications/initialized`, and then use that session for `tools/list` and `tools/call`.

  • 1. The client sends `initialize` to the public MCP endpoint.
  • 2. The server returns `mcp-session-id` and the negotiated protocol version.
  • 3. The client sends `notifications/initialized`, then uses that session for `tools/list` and `tools/call`.

Server capabilities (MCP 2025-11-25)

The server advertises capabilities in its initialize response. The tasks capability enables task-augmented invocation on architect.validate for compatible clients.

Clients that advertise the tasks capability can task-augment any architect.validate call by adding task: { ttl: <ms> } to params. The server returns a CreateTaskResult immediately and finishes the work in the background.

  • tasks/get · status and pollInterval
  • tasks/result · terminal payload
  • tasks/list · per-user paginated list
  • tasks/cancel · cancel in-flight task

Push updates arrive on notifications/tasks/status. taskId == run_id (PR-1 single-source); me.validation_history(run_id=<taskId>) and tasks/result(taskId) route to the same persisted row. Sync clients see no change.

Current scope (PR-1): only architect.validate adopts SEP-1686 in this release. architect.validate_consensus and architect.certify are sync-only today; task augmentation extends to both in the next release with full parent-child + cert-lifecycle design. Use the me.validation_history(run_id=...) recovery pattern described above for the sync tools until then.

Public tools (12)

Anonymous, read-only. No API key required.

Use targeted calls, principles.get(slug) or examples.get(slug), rather than bulk listing when you already know what you need. Each unnecessary list call adds tokens your model has to process.

  • principles.list(cluster?)
  • clusters.list()
  • principles.get(slug)
  • clusters.get(slug)
  • examples.get(slug)
  • principles.search(query, limit?)
  • examples.search(query, principle_ids?, difficulty?, library?, limit?)
  • assets.list()
  • guides.list(audience?, format?, level?)
  • guides.get(slug)
  • guides.search(query, audience?, level?, limit?)
  • signals.feedback(rating, note?, …)

Authenticated tools (12)

Firebase Bearer token required. Plan tier depends on the tool: breakdown below.

Any signed-in plan (6), Basic and up

  • me.learning_path()
  • me.coaching_context()
  • me.add_evidence(course_slug, stage_id, note)
  • handoffs.operator(task, …)
  • handoffs.partnership(task, …)
  • handoffs.agency(task, …)

Pro or Teams (5)

architect.* and team.summarize accept private_session=true to skip server-side logging.

  • architect.validate(implementation_context, focus_area?, task?, language?, repository?, files?, goals?, example_limit?, private_session?) · supports MCP Tasks (params.task: {ttl:<ms>})
  • architect.validate_consensus(implementation_context, n?, focus_area?, …)
  • architect.certify(implementation_context, …)
  • me.validation_history(limit?)
  • signals.report(event_type, surface, perceived_value, …)

Teams only (1)

  • team.summarize(days_back?, private_session?)

Verified compatibility

Endpoint health and native client registration are not the same thing. This section separates the transport reality, the recommended fallback, and the highest-confidence setup path.

Verified with notes

Claude Code

Skill pack strongly recommended, live MCP for structured queries.

The transport is Streamable HTTP with a session lifecycle. If the client does not register tools immediately, keep the skill installed and verify the MCP with the setup flow below.

Verified with notes

Cursor

Rules export for persistent context, MCP for live retrieval.

The best experience comes from the rules + MCP combination, not from the endpoint alone.

Recommended setup

Codex

Use `codex mcp add` or `~/.codex/config.toml` for the live server and JSON/Markdown as local fallback.

The local fallback avoids stalls when you only need the doctrine without a live call.

Recommended setup

Windsurf

Workspace rule for persistent context, with AGENTS.md as the cross-tool companion.

The cleanest path is the workspace rule plus AGENTS.md in the repo when you want the same doctrine outside Windsurf too.

Recommended setup

GitHub Copilot

Repository instructions for persistent guidance, with AGENTS.md as the shared companion file.

Copilot works best with short, stable repo instructions. AGENTS.md acts as the extra layer when you want consistency with other tools.

Recommended setup

Gemini CLI

GEMINI.md as persistent context, with llms.txt or prompt packs as local support.

The simplest path is GEMINI.md at project root, then llms.txt or prompt packs when you want additional context without live retrieval.

Recommended setup

DeepSeek

Static prompt pack for local or open-weight workflows, with llms.txt as support.

DeepSeek does not use MCP as the primary path here. The correct setup is the prompt pack plus llms.txt as the lightweight fallback.

Recommended setup

Qwen

Static prompt pack for Qwen or local runtimes without MCP dependency.

The cleanest path is the Qwen prompt pack with llms.txt as the discovery and quick-recall companion document.

Fully supported

Raw HTTP / curl

Ideal for QA, debugging, and transport verification.

Use initialize, notifications/initialized, tools/list, and tools/call to verify the live endpoint.

Doctrine audit command

A Claude Code slash command that fetches all principles from the live MCP server, navigates key site pages with Playwright, and produces a gap report aligned to the four doctrine clusters: delegation, visibility, trust, and orchestration.
Loads all 10 principles and cluster summaries via MCP
Screenshots key pages and evaluates them against each cluster
Reports alignment, partial gaps, and missing signals with component-level references
Run with /audit-doctrine after any significant UI change
Download command file

Verify your setup

Test the transport first, then the first tool, then a real prompt. This avoids the false impression of an endpoint that is healthy but not operational.
  1. Add the server with the config block below.
  2. Confirm that the client shows the server or that the endpoint responds to `initialize`.
  3. Run `clusters.list` as the first proof call.
  4. Use one of the kickoff prompts for an audit, example search, or principle lookup.

Kickoff prompts

Use these prompts to start from a real task instead of spending the first turn explaining setup and context.

Architecture audit

Use the blueprint as an audit framework. List the clusters first, then propose which principles to use to assess this agent architecture and which examples to read next.

Example lookup

Search examples for orchestration, visibility, and steering. Group them by principle and tell me which ones are worth reading first.

Principle explainer

Explain the most relevant principle for this workflow with its definition, rationale, risk, and one linked example.

Download prompt pack

Initialize example

Use this call to verify that the endpoint negotiates the session correctly and returns `mcp-session-id`.
curl -i -X POST "https://aidesignblueprint.com/mcp" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "manual-check",
      "version": "1.0.0"
    }
  }
}'

Keep the `mcp-session-id` value returned in the headers. You need it for `notifications/initialized`, `tools/list`, and every later `tools/call`.

First proof call

After `initialize`, use `clusters.list` as the minimum proof call. If this passes, the public surface is operational.
curl -i -X POST "https://aidesignblueprint.com/mcp" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "clusters.list",
    "arguments": {}
  }
}'

Replace `&lt;session-id&gt;` with the value returned by `initialize`. From there, the next step is to use one of the kickoff prompts for a real doctrine query.

What does this public agent release actually include?

It includes a read-only MCP surface for principle and example retrieval, deterministic doctrine exports, and installable assets for local agent setups. It does not yet include protected validation or team governance.

Also in this section

Public vs protectedTrust and data handlingStart here