MCP_COVERAGE_PLAN

Status: proposed Branch: feat/mcp-coverage-skills

1. Where we actually are#

1.1 The security finding, stated plainly#

AEXY_ENABLE_TEMPORAL is not an access control. It is a flag the caller sets on their own machine. Combined with the temporal tools talking straight to the Temporal frontend rather than through Aexy, any holder of any aexy_ API token can signal, cancel, and terminate live production workflows, and Aexy has no record that it happened. required_permission: can_view_agents on the mcp app gates the settings page, not the tools.

This is the single highest-priority item in the plan and it is fixed in Phase 1, before any of the feature work.

1.2 Setup instructions — every client is wrong or missing#

2. Decisions taken#

1. mcp-server stays external, but publishes a generated tools.json manifest that this repo consumes at build time. No more hand-maintained catalog.
2. Full remote MCP: streamable HTTP endpoint + OAuth 2.1 with authorization-server metadata and dynamic client registration. This is what ChatGPT connectors and Claude web/desktop custom connectors require, and it is where server-side access flags belong.
3. Skills are curated + admin-approved per workspace. Crawled skills land unreviewed; a workspace admin approves before anyone can load one. Loads are audit-logged.

3. Workstreams#

WS1 — Tool manifest and parity (kills the drift)#

Mirrors the pattern this repo already uses for the app catalog (backend/scripts/dump_app_catalog.py + two parity tests).

In aexy-io/mcp-server:

• scripts/dump_tool_manifest.py walks the live tool registry and emits tools.json:

  { "version": "0.4.0", "generated_at": "...",
    "categories": [{ "key": "sprints", "name": "Sprint Management",
      "tools": [{ "name": "aexy_sprints", "description": "...",
                  "capability": "mcp.sprints", "mutating": true,
                  "input_schema": { ... } }] }] }
  

• CI job asserts tools.json is current, and publishes it to a release asset + PyPI sdist.

In this repo:

• frontend/scripts/fetch-tool-manifest.js — pulls the pinned manifest into frontend/src/config/mcpTools.generated.json, wired into prebuild alongside merge-messages.js. Pinned by version, committed, so builds stay hermetic.
• Delete the hand-written TOOL_CATEGORIES array (page.tsx:44) and read the manifest.
• Tool names/descriptions come from the manifest; i18n keeps only category names and page chrome. This ends the "update the array AND the i18n keys" rule in the file's comment.
• frontend/src/test/mcpManifestParity.test.ts — every capability string in the manifest exists as a module on the mcp app in appDefinitions.ts. A tool with no grant fails the build.

WS2 — Remote transport + OAuth 2.1 (unblocks ChatGPT, Claude Desktop, Claude web)#

New backend router backend/src/aexy/api/mcp.py, mounted in api/__init__.py.

• POST /api/v1/mcp — streamable HTTP transport (MCP spec 2025-06-18). initialize, tools/list, tools/call, prompts/list, prompts/get, resources/*.
• GET /.well-known/oauth-authorization-server and GET /.well-known/oauth-protected-resource — mounted at the app root, not under /api/v1, per RFC 8414 / RFC 9728. Requires a route registration outside the versioned prefix in main.py.
• POST /api/v1/mcp/oauth/register — dynamic client registration (RFC 7591). ChatGPT and Claude Desktop both register themselves; without this the connector UIs cannot complete setup.
• Authorization code + PKCE, reusing the existing api/auth.py session for the consent screen. New consent page frontend/src/app/auth/mcp-consent/page.tsx showing exactly which capabilities the client is asking for.
• Bearer tokens: reuse ApiToken with a new token_kind column (personal | oauth) and a client_id FK, so one revoke path covers both.

New models: McpOAuthClient, McpAuthorizationCode. Migration backend/scripts/migrate_mcp_oauth.sql.

The server-side handler shares the tool implementations with the stdio server by importing the published aexy-mcp package — the stdio entrypoint and the HTTP handler are two transports over one registry, not two codebases.

WS3 — Access as org access, with a real Temporal flag#

This is the item the current design gets wrong, so it is specified in full.

3a. Capabilities become modules on the mcp app.

Per CLAUDE.md, edit both files and regenerate the fixture:

# backend/src/aexy/models/app_definitions.py:429
"mcp": {
    ...
    "modules": {
        "sprints": True, "crm": True, "agents": True, "email_gtm": True,
        "analytics": True, "platform": True,
        "temporal": False,   # off in every bundle — see 3b
    },
},

Same shape in frontend/src/config/appDefinitions.ts:330, then:

cd backend && python scripts/dump_app_catalog.py

temporal: False in all four bundles. It is granted deliberately, never inherited.

3b. Temporal tools stop talking to Temporal.

New router backend/src/aexy/api/temporal_admin.py exposing the 8 operations (list_workflows, describe, history, query, signal, cancel, list_schedules, system_status) over the existing Temporal client the backend already holds.

• Read operations require module mcp.temporal.
• Mutating operations (signal, cancel) additionally require a new permission can_manage_temporal, and write an audit row.
• The MCP server calls these endpoints like every other tool.

Effect: TEMPORAL_ADDRESS, TEMPORAL_NAMESPACE and AEXY_ENABLE_TEMPORAL disappear from every client config. The client can no longer reach Temporal directly, and the flag is no longer self-asserted. Remove all three from page.tsx and the i18n files.

3c. Capability endpoint.

GET /api/v1/mcp/capabilities → for the authenticated token:

{ "developer_id": "...", "workspace_id": "...",
  "capabilities": ["mcp.sprints", "mcp.crm", "mcp.platform"],
  "denied": [{ "capability": "mcp.temporal", "reason": "not_granted" }] }

Resolved by the existing AppAccessService.get_effective_access — no parallel authz system. Both transports call it: stdio on session start, HTTP per session. tools/list returns only permitted tools, so the model never burns turns on calls that will 403.

Defence in depth: tools/call re-checks server-side. Filtering the list is an ergonomics optimisation, never the gate — a client that ignores tools/list still gets a 403.

3d. Token scoping.

Add to api_tokens (migration backend/scripts/migrate_mcp_capabilities.sql):

Token-create UI at /settings/api-tokens gains capability checkboxes, so a read-only CI token is possible.

3e. Seeding.

• mcp.temporal seeded true for workspace owners and admins only.
• Backfill backend/scripts/backfill_mcp_capabilities.py: for every existing member, derive non-temporal MCP modules from the apps they already have; leave temporal off.
• Admin UI: existing app-access matrix picks up the new modules for free — one row per capability, temporal visually flagged as privileged.

WS4 — Client setup, correct and complete#

Rewrite the clientSetup section of page.tsx as six tabs, each with both a local (stdio) and a remote (HTTP) variant once WS2 lands:

Claude Code · Claude Desktop · ChatGPT · Codex · Cursor / VS Code · Other

Concrete corrections (see §1.2). Recommended snippets after WS2:

# Claude Code — remote, one line
claude mcp add --transport http aexy https://api.aexy.io/mcp

// Claude Code / Cursor — local stdio, .mcp.json at project root
{ "mcpServers": { "aexy": {
    "command": "uvx", "args": ["aexy-mcp@latest"],
    "env": { "AEXY_API_URL": "https://api.aexy.io/api/v1",
             "AEXY_API_TOKEN": "${AEXY_API_TOKEN}" } } } }

# Codex — ~/.codex/config.toml
[mcp_servers.aexy]
command = "uvx"
args = ["aexy-mcp@latest"]
env = { AEXY_API_URL = "https://api.aexy.io/api/v1", AEXY_API_TOKEN = "..." }

ChatGPT: Settings → Connectors → Create, URL https://api.aexy.io/mcp, OAuth completes in browser. No token pasting.

Also on the page: render the caller's actual capabilities from /mcp/capabilities, so a developer sees which tools they will get before they wire anything up, and why temporal is missing.

WS5 — Documentation#

• docs/mcp.md — new, following the shape of docs/crm.md / docs/ai-agents.md: what MCP is, the six client setups, the tool catalog generated from the manifest, the capability model, the temporal grant, troubleshooting.
• docs/guides/mcp-access-control.md — admin-facing: granting capabilities, scoped tokens, reading the audit log.
• docs/guides/skills.md — /aexy_skill, publishing, the approval workflow.
• Register all three in docs/README.md and frontend/public/docs/index.json, and mirror into frontend/public/docs/ (the existing duplication convention).
• frontend/scripts/generate-mcp-doc.js regenerates the tool-catalog section of docs/mcp.md from the manifest, in prebuild. The prose is hand-written; the table is not.

WS6 — Tool coverage#

31 tools against 120 routers, but one tool per router is the wrong target — a 120-tool surface degrades model selection badly. Keep the existing resource-oriented shape (one tool per domain, action parameter) and close the domain gaps:

Takes the surface to ~43 tools — near the practical ceiling, which is why the long tail should be reached through the existing aexy_api escape hatch instead of new tools. Upgrade it with an aexy_api_discover companion that queries the backend OpenAPI schema, so an agent can find and call any of the 120 routers without us minting a tool for each.

Every new tool declares its capability in the manifest; WS1's parity test refuses any tool whose capability has no matching module.

WS7 — /aexy_skill load and /aexy_skill search#

How the slash command actually appears. MCP prompts surface in Claude Code as /mcp__<server>__<prompt>. To get literally /aexy_skill, ship both:

1. An MCP prompt named aexy_skill taking one string argument, parsing load <name> / search <term> / list / publish <path>. Works in any prompt-aware client.
2. A Claude Code slash-command file .claude/commands/aexy_skill.md in the onboarding scaffold, so the bare /aexy_skill form works too.

Both delegate to MCP tools, so non-interactive agents get the same functionality:

Backend. New models — Skill, SkillVersion (content-hash keyed, immutable), SkillSource, WorkspaceSkillApproval, SkillLoadEvent. Router api/skills.py, service services/skill_service.py, migration migrate_skills.sql. Register models in models/__init__.py (they are not auto-discovered).

Search. Postgres tsvector over name + description + frontmatter keywords to start; add a pgvector embedding column in a follow-up once there is a corpus worth embedding. PG18 is already the target so both are available.

Capability. mcp.skills module; publishing additionally requires can_manage_workspace.

WS8 — Marketplace curation from the internet#

Ingestion. SkillSource rows are an allowlist of GitHub repos/orgs. Seed: anthropics/skills. A Temporal schedule skill_catalog_sync (queue SYNC) runs activity sync_skill_sources — crawl, parse SKILL.md frontmatter (name, description, license), upsert a SkillVersion per content hash. Add to ACTIVITY_CONFIG in temporal/dispatch.py with STANDARD_RETRY and a stable workflow_id per source.

Curation pipeline. unreviewed → scanned → approved(workspace) → published.

• scan_skill_version activity flags: network egress to non-allowlisted hosts, base64 blobs, instructions that name aexy_* tools or ask to widen scope, licence absent or non-permissive.
• Findings render in the admin approval UI at /settings/skills, next to a full diff of the skill body. Approval is per workspace, per version — a new upstream version re-enters review rather than auto-updating.

The trust rule, non-negotiable. A skill's text is data. It never widens the caller's capability grant. Capability is resolved server-side per tools/call from AppAccessService, so a skill that instructs the agent to call temporal_signal_workflow gets a 403 from a caller without mcp.temporal, exactly as if the skill had said nothing. WS3's defence-in-depth check is what makes WS8 safe to build at all — the ordering below is not negotiable.

Attribution. Store source_url, license, upstream_commit per version; surface them on load. Skip any source without a licence we can honour.

4. Sequencing#

Phase 1 before Phase 2 matters: shipping a remote endpoint while AEXY_ENABLE_TEMPORAL is still the only gate would put self-asserted workflow-termination on the public internet.

5. Risks#

• OAuth 2.1 + DCR is the hard part. ChatGPT and Claude Desktop are strict about metadata discovery and will fail with unhelpful errors. Budget real time; test against both connector UIs early rather than against a spec document.
• Well-known routes escape /api/v1. Mounting them needs a change in main.py outside the versioned prefix, plus whatever ingress sits in front in production.
• Tool-count ceiling. 43 tools is workable; each further addition costs selection accuracy for every call. Route the long tail through aexy_api + aexy_api_discover.
• Manifest pinning. A stale pin means the page under-reports tools; a floating pin makes builds non-hermetic. Pin by version, commit the fetched file, bump deliberately.
• Crawled skills are an injection surface. Mitigated by Phase 1 ordering, per-workspace approval, per-version re-review, and server-side capability checks that no skill text can influence.
• api/mcp.py vs the frontend route group. The frontend already owns /mcp; the backend endpoint is /api/v1/mcp plus a root-level /mcp for remote clients. Confirm the production ingress routes these to the right service before Phase 2 ships.