Skip to content

Virtual and concrete MCP servers #9

Closed

Description

@jayjfletcher

Problem

Agents come in two kinds: virtual agents live entirely in the database (versioned
instructions, a tool list, sub-agents, published version runs), and concrete agents
are classes whose prompt and toolset Cortex can override. MCP servers have only half
of that: the McpServer domain registers class-based servers and overrides their
instructions. There is no way to define a server in the database, and a class-based
server's tool list cannot be changed without code.

Desired outcome

  • Virtual servers: an MCP server defined entirely in Cortex — name, slug,
    description, versioned instructions (immutable versions, the published one is
    served), and a list of exposed tools drawn from the tool registry plus
    virtual/concrete agents exposed as tools. Served over MCP at its own route.
    CRUD, versions and publish through actions, HTTP API, Cortex MCP tools and Atrium
    screens, like virtual agents.
  • Concrete servers: class-based servers (today's McpServer domain) gain the
    same overrides concrete agents have — instructions (already there) plus a
    replaceable tool list — and line up with ConcreteAgent in naming and shape:
    the McpServer domain is renamed ConcreteServer (stored names and morph
    aliases kept), and virtual servers get a new VirtualServer domain.

Acceptance hints

  • Virtual server create/update/delete/list/show, versions create/list/show/publish:
    one action each, HTTP request + MCP request on the same action, parity tests.
  • An unpublished virtual server is not served (like VirtualAgentNotPublishedException).
  • Concrete server tool override: a non-null list replaces the code-declared tools;
    delete override restores code defaults.
  • Tables via cortex.tables, policies per model, model events, ArchTest green,
    RenamedTables mode covers the new flows.
  • Atrium screens for both kinds.

Out of scope

  • Proxying or aggregating remote (third-party) MCP servers.
  • MCP resources and prompts on virtual servers (tools only) unless decided otherwise.

Activity

  1. jayjfletcher commented on Oct 23, 2026

    @jayjfletcher
    MemberAuthor

    Decisions recorded for this job (docs/agent/specs/2026-10-23-1917-virtual-and-concrete-mcp-servers/decisions.md):

    • D-001 — Create the issue as drafted.
    • D-002 — A virtual server exposes registered tools plus virtual/concrete agents as tools.
    • D-003 — The existing McpServer domain is renamed ConcreteServer (stored names and morph aliases kept), and a new VirtualServer domain is added.
  2. jayjfletcher commented on Oct 23, 2026

    @jayjfletcher
    MemberAuthor

    Decisions recorded (answered in RingMaster):

    • D-004 — Scope of the McpServer → ConcreteServer rename: classes and namespaces only; table keys, HTTP routes/names, MCP tool names, config keys and registered server names stay (no breaking change).
    • D-005 — Storage of a concrete server's tool override: new nullable tools column on the existing mcp_instructions override row (new migration), mirroring ConcreteAgentOverrideModel.

    Still open before shaping continues: standards list (Q-004), how virtual servers are served over MCP (Q-005), where a virtual server's tool/agent lists live (Q-006).

  3. jayjfletcher commented on Oct 23, 2026

    @jayjfletcher
    MemberAuthor

    More decisions recorded (answered in RingMaster):

    • D-006 — Standards: use the list proposed in shape.md.
    • D-007 — Serving virtual servers: one config-gated route with the server slug in the path (cortex.mcp.virtual.enabled, off by default), resolved per request.
    • D-008 — Virtual server tool/agent lists: on the server row, like virtual agents (tools json, concrete_agents json, pivot to virtual agents); only instructions are versioned.

    All open shaping questions are answered; shaping resumes.

  4. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    Decisions recorded (spec-review, answered in RingMaster):

    • D-009 — Concrete server tool override policy: dedicated updateTools policy ability; the bundled policy allows it, like every other Cortex ability.
    • D-010 — Unpublished virtual server over MCP: clients get a distinct message from VirtualServerNotPublishedException, not the unknown-slug Not found..

    Still open before spec review continues: old-FQCN shims (Q-009), #[LockedServerTools] (Q-010), one spec or two (Q-011), tool/agent name clash at serve time (Q-012), empty virtual-route middleware (Q-013), stale references (Q-014).

  5. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    Decisions recorded (spec-review, answered in RingMaster):

    • D-011 — Old namespace after the rename: host servers on Domains\McpServer\Support\Server / Concerns\HasVersionedInstructions keep working through class_alias shims at the old FQCNs, deprecated (removed next major), tested.
    • D-012 — No #[LockedServerTools]: no public attribute; only the cortex server is non-overridable, as a registry rule.
    • D-013 — Two specs: rename + concrete server tool override first, virtual servers in a follow-up spec.
    • D-014 — Serve-time name clash on a virtual server: the registered tool wins, warning logged.
    • D-015 — Empty virtual-route middleware: fail closed; the route is not registered (with a warning saying why) until cortex.mcp.virtual.middleware is non-empty.

    Still open before spec review continues: stale references at serve time (Q-014).

  6. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    Decision D-016 (answered in RingMaster): stale references at serve time.

    Deleted, unpublished or unregistered tools/agents in a concrete server's tool override (and, in the follow-up spec, a virtual server's lists) are skipped with a logged warning; the rest are served, and the resource reports the missing entries (missing_tools).

  7. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    Decision D-017 (raised by spec review, answered in RingMaster)

    Q: How are host apps handled whose config/cortex.php policies map is keyed by the old McpServer model FQCNs (now silently ignored, falling back to the allow-all bundled policy)?

    Choice: ConcreteServerServiceProvider remaps old policy keys to the new classes and logs a deprecation warning (class aliases for the two models and two policies), tested.

    Still open: Q-015 (what deleting a server's instructions does when the override row also holds a tool override).

  8. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    Decision D-018 (spec-review, answered in RingMaster)

    Q: What does DELETE servers/{server}/instructions (and delete-server-instructions) do when the override row also holds a tool override?

    Choice: Clear instructions only (delete versions, null the published version); remove the row only when tools is null; a separate action clears the tool override.

  9. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    Decisions recorded for spec 2026-10-23-1917-virtual-and-concrete-mcp-servers (raised in spec review, answered in RingMaster):

    • D-019 Clear tool override: ClearConcreteServerToolsAction; DELETE cortex/servers/{server}/tools (cortex.servers.tools.destroy); MCP tool clear-server-tools; ability updateTools; events ConcreteServerTools{Clearing,Cleared}ActionEvent.
    • D-020 Model/policy shims and policy-key remap stay in this spec.
    • D-021 Entry matching both a code tool and a registered Cortex tool: code wins, warning logged at serve time.
    • D-022 Entry whose tool throws while being built: skipped, warning logged, rest served.
    • D-023 Rollback-cache and unique-race tests run with DatabaseMigrations on file-based SQLite.
    • D-024 Migration test is staged (pre-insert, migrate, rollback).

    Spec goes back to spec review.

  10. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    Decisions recorded for spec 2026-10-23-1917-virtual-and-concrete-mcp-servers (raised in spec review, answered in RingMaster):

    • D-025 The order test (AC 10a) observes the ServerContext tools through a reflection helper shared with the vendor pin test.
    • D-026 The server context is memoized per request; tests assert exactly one warning per stale, failing or ambiguous entry per client request.

    Still open: Q-022 to Q-026 (shim loading, rebuild-failure fallback, version delete mode, updateTools guest default on upgrade, CI drivers). Spec review resumes once those are answered.

  11. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    More decisions recorded for spec 2026-10-23-1917-virtual-and-concrete-mcp-servers (raised in spec review, answered in RingMaster):

    • D-027 Compatibility shims are lazy: an spl_autoload_register fallback in the autoload.files file aliases an old Domains\McpServer\ name only when requested.
    • D-028 A failed ServerContext rebuild logs a warning and serves the code-declared tools unchanged.
    • D-029 DeleteMcpInstructionAction deletes versions per model, firing model events and audit entries.
    • D-030 The bundled updateTools default stays; a one-time boot warning fires outside local when guests are allowed it.
    • D-031 Race and migration tests run on SQLite only.

    No questions left open; spec goes back to spec review.

  12. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    Decisions recorded (answered in RingMaster):

    • D-032 Cortex server screen: hide the tool editor and the restore button for non-overridable servers.
    • D-033 Tool update authorized by the server-level updateTools ability only, documented as a trust boundary (per-tool ability as a follow-up).
    • D-034 Host without the new migration: degrade, treat a missing tools column as no override and log one warning.
    • D-035 Stale, ambiguous and corrupt-value warnings: cache-based rate limit per server+entry with a TTL.
    • D-036 Stored tool order is a product promise: asserted on the resource tools field plus the server context.
    • D-037 Guest boot warning: resettable once-per-process flag plus a method that re-runs the check, called from the booted callback.
    • D-038 Autoload shim: test asserts vendor/composer/autoload_files.php contains the shim, and CI runs composer dump-autoload.

    Spec goes back to spec review.

  13. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    Decisions recorded (spec 2026-10-23-1917-virtual-and-concrete-mcp-servers, answered in RingMaster):

    • D-039 Guest boot warning with mixed per-server results: log once if any overridable server is allowed updateTools for guests, naming those servers.
    • D-040 Docs test checks route, tool and ability names and the snippet only; the Keen skip and the AC 2 baseline become machine checks; the ArchTest exclusion-list review becomes a process note.

    Still open from spec review: Q-036 (CI scope), Q-037 (already-published migrations), Q-038 (alias breadth), Q-039 (warning rate-limit TTL).

  14. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    Decisions recorded for the spec (answered in RingMaster, raised by spec review):

    • D-041: CI change is in scope. Add refactor-circus/keen to require-dev and add a composer dump-autoload step to CI.
    • D-042: Idempotent tools migration. The new tools column migration is idempotent; the docs tell hosts that already published Cortex migrations to copy just that file.
    • D-043: Narrow compatibility layer. Keep the shims for Support\Server, the trait, the two models and the two policies; document the break for events, actions, Data and exceptions in the CHANGELOG and README (drain queues, re-register listeners).
    • D-044: Warning rate-limit TTL is configurable. The TTL lives in a new key in config/cortex.php.
  15. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    More decisions recorded for spec 2026-10-23-1917-virtual-and-concrete-mcp-servers (raised in spec review, answered in RingMaster):

    • D-045 Warning rate-limit TTL key is cortex.mcp.warning_ttl, default 3600 seconds (int cast, hard default on every read).
    • D-046 Bundled updateTools default unchanged: D-009/D-030 stand (guest-allowed plus boot warning); any future gating key defaults to false.
    • D-047 Rebuild-failure warning reuses the D-035 cache limiter, keyed by server plus exception class.
    • D-048 Lazy autoload fallback logs a clear "moved to ..." message for unshimmed old names, without aliasing (D-043 unchanged).
    • D-049 Tools update action also re-reads under lockForUpdate(); non-SQLite behaviour documented as untested.
    • D-050 All hardening layers stay in this spec.
    • D-051 Served-order test also asserts tools/list order, after confirming laravel/mcp preserves it.

    No questions left open; spec goes back to spec review.

  16. 5 remaining items

  17. jayjfletcher commented on Oct 24, 2026

    @jayjfletcher
    MemberAuthor

    Build resumed (factory workflow) after D-054. Group 1 continues from task 1.3; finished tasks stay ticked.

  18. jayjfletcher commented on Oct 25, 2026

    @jayjfletcher
    MemberAuthor

    Ring Master factory resumed the build (run wf_4b69ba3b-4de): group 1 is done, groups 2–8 are building now.

  19. jayjfletcher commented on Oct 25, 2026

    @jayjfletcher
    MemberAuthor

    Ring Master: build restarted from group 2 after rework (worktree now installs every refactor-circus package from its local checkout with composer local:install).

  20. jayjfletcher commented on Oct 25, 2026

    @jayjfletcher
    MemberAuthor

    Ring Master: build restarted (rework 2). Group 2 is split into class-name shims (2), morph aliases (10), policy-key remap (11) and Keen/CI checks (12); the factory builds those, then groups 3–8. New commits land on #10.

  21. jayjfletcher commented on Oct 25, 2026

    @jayjfletcher
    MemberAuthor

    Ring Master: factory build resumed (2026-10-24) for groups 3–12; groups 1, 2 and 9 are already built.

  22. jayjfletcher commented on Oct 25, 2026

    @jayjfletcher
    MemberAuthor

    Decision D-055 (answered in RingMaster, raised by build)

    When the missing-column check itself throws (e.g. the schema query fails because the connection is down), serving treats that call as "no tool override": the code tools are served with the instructions override still applied, a rate-limited warning is logged (server name + exception message, limiter subject column-check:<exception class>), and nothing is memoized, so the next request checks again.

  23. jayjfletcher commented on Oct 25, 2026

    @jayjfletcher
    MemberAuthor

    Build resumed (Ring Master factory) after D-055: group 3 follow-up (throwing column check), then groups 4–8.

  24. jayjfletcher commented on Oct 25, 2026

    @jayjfletcher
    MemberAuthor

    Decision recorded (D-056, answered in RingMaster): an MCP instructions delete writes one Keen audit entry (mcp_instruction.deleted); per-version deletes show only as model events. README and CHANGELOG will say so.

  25. jayjfletcher commented on Oct 25, 2026

    @jayjfletcher
    MemberAuthor

    Build resumed (factory, groups 6-8) after D-056.

  26. jayjfletcher commented on Oct 25, 2026

    @jayjfletcher
    MemberAuthor

    Decision D-057 (raised by build, answered in RingMaster, 2026-10-25)

    Q: What should DELETE cortex/servers/{server}/instructions and delete-server-instructions answer?

    Choice: Answer 204 and text whenever the row is removed, as today. When the row survives because it still holds a tool override, answer 200 with McpInstructionResource, and the tool answers that resource as structured content.

  27. jayjfletcher commented on Oct 25, 2026

    @jayjfletcher
    MemberAuthor

    Build resumed after D-057 (instructions delete response): finishing group 6 (tasks 6.4–6.6), then groups 7 and 8, then review.

  28. jayjfletcher commented on Oct 25, 2026

    @jayjfletcher
    MemberAuthor

    Decision D-058 (answered in RingMaster, raised by build)

    The ArchTest security-preset failure accepted locally in D-054 (unserialize in Atrium's SearchRegistry.php:270, flagged because composer local:install symlinks Atrium outside vendor/) will be fixed at the source: a separate Atrium job stops SearchRegistry from using unserialize (for example by passing search results as JSON). After that, composer local:update runs in Cortex and the gate expects composer test fully green.

    This job's build is on hold until the Atrium fix lands.

  29. jayjfletcher commented on Oct 26, 2026

    @jayjfletcher
    MemberAuthor

    Ring Master: build resumed. Atrium's SearchRegistry no longer uses unserialize (D-058), so the local ArchTest security-preset failure is gone; running the factory review rounds again.

  30. added a commit that references this issue on Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions