Repository navigation
Closed
Description
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
McpServerdomain) gain the
same overrides concrete agents have — instructions (already there) plus a
replaceable tool list — and line up withConcreteAgentin naming and shape:
theMcpServerdomain is renamedConcreteServer(stored names and morph
aliases kept), and virtual servers get a newVirtualServerdomain.
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.
Metadata
Metadata
Assignees
Labels
No labels
Activity
jayjfletcher commentedon Oct 23, 2026
Decisions recorded for this job (
docs/agent/specs/2026-10-23-1917-virtual-and-concrete-mcp-servers/decisions.md):McpServerdomain is renamedConcreteServer(stored names and morph aliases kept), and a newVirtualServerdomain is added.jayjfletcher commentedon Oct 23, 2026
Decisions recorded (answered in RingMaster):
toolscolumn on the existingmcp_instructionsoverride row (new migration), mirroringConcreteAgentOverrideModel.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).
jayjfletcher commentedon Oct 23, 2026
More decisions recorded (answered in RingMaster):
cortex.mcp.virtual.enabled, off by default), resolved per request.All open shaping questions are answered; shaping resumes.
jayjfletcher commentedon Oct 24, 2026
Decisions recorded (spec-review, answered in RingMaster):
updateToolspolicy ability; the bundled policy allows it, like every other Cortex ability.VirtualServerNotPublishedException, not the unknown-slugNot 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).jayjfletcher commentedon Oct 24, 2026
Decisions recorded (spec-review, answered in RingMaster):
Domains\McpServer\Support\Server/Concerns\HasVersionedInstructionskeep working throughclass_aliasshims at the old FQCNs, deprecated (removed next major), tested.#[LockedServerTools]: no public attribute; only thecortexserver is non-overridable, as a registry rule.cortex.mcp.virtual.middlewareis non-empty.Still open before spec review continues: stale references at serve time (Q-014).
jayjfletcher commentedon Oct 24, 2026
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).jayjfletcher commentedon Oct 24, 2026
Decision D-017 (raised by spec review, answered in RingMaster)
Q: How are host apps handled whose
config/cortex.phppoliciesmap is keyed by the old McpServer model FQCNs (now silently ignored, falling back to the allow-all bundled policy)?Choice:
ConcreteServerServiceProviderremaps 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).
jayjfletcher commentedon Oct 24, 2026
Decision D-018 (spec-review, answered in RingMaster)
Q: What does
DELETE servers/{server}/instructions(anddelete-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
toolsis null; a separate action clears the tool override.jayjfletcher commentedon Oct 24, 2026
Decisions recorded for spec
2026-10-23-1917-virtual-and-concrete-mcp-servers(raised in spec review, answered in RingMaster):ClearConcreteServerToolsAction;DELETE cortex/servers/{server}/tools(cortex.servers.tools.destroy); MCP toolclear-server-tools; abilityupdateTools; eventsConcreteServerTools{Clearing,Cleared}ActionEvent.DatabaseMigrationson file-based SQLite.Spec goes back to spec review.
jayjfletcher commentedon Oct 24, 2026
Decisions recorded for spec
2026-10-23-1917-virtual-and-concrete-mcp-servers(raised in spec review, answered in RingMaster):ServerContexttools through a reflection helper shared with the vendor pin test.Still open: Q-022 to Q-026 (shim loading, rebuild-failure fallback, version delete mode,
updateToolsguest default on upgrade, CI drivers). Spec review resumes once those are answered.jayjfletcher commentedon Oct 24, 2026
More decisions recorded for spec
2026-10-23-1917-virtual-and-concrete-mcp-servers(raised in spec review, answered in RingMaster):spl_autoload_registerfallback in theautoload.filesfile aliases an oldDomains\McpServer\name only when requested.ServerContextrebuild logs a warning and serves the code-declared tools unchanged.DeleteMcpInstructionActiondeletes versions per model, firing model events and audit entries.updateToolsdefault stays; a one-time boot warning fires outsidelocalwhen guests are allowed it.No questions left open; spec goes back to spec review.
jayjfletcher commentedon Oct 24, 2026
Decisions recorded (answered in RingMaster):
updateToolsability only, documented as a trust boundary (per-tool ability as a follow-up).toolscolumn as no override and log one warning.toolsfield plus the server context.vendor/composer/autoload_files.phpcontains the shim, and CI runscomposer dump-autoload.Spec goes back to spec review.
jayjfletcher commentedon Oct 24, 2026
Decisions recorded (spec 2026-10-23-1917-virtual-and-concrete-mcp-servers, answered in RingMaster):
updateToolsfor guests, naming those servers.Still open from spec review: Q-036 (CI scope), Q-037 (already-published migrations), Q-038 (alias breadth), Q-039 (warning rate-limit TTL).
jayjfletcher commentedon Oct 24, 2026
Decisions recorded for the spec (answered in RingMaster, raised by spec review):
refactor-circus/keentorequire-devand add acomposer dump-autoloadstep to CI.toolscolumn migration is idempotent; the docs tell hosts that already published Cortex migrations to copy just that file.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).config/cortex.php.jayjfletcher commentedon Oct 24, 2026
More decisions recorded for spec
2026-10-23-1917-virtual-and-concrete-mcp-servers(raised in spec review, answered in RingMaster):cortex.mcp.warning_ttl, default 3600 seconds (int cast, hard default on every read).updateToolsdefault unchanged: D-009/D-030 stand (guest-allowed plus boot warning); any future gating key defaults to false.lockForUpdate(); non-SQLite behaviour documented as untested.tools/listorder, after confirming laravel/mcp preserves it.No questions left open; spec goes back to spec review.
5 remaining items
jayjfletcher commentedon Oct 24, 2026
Build resumed (factory workflow) after D-054. Group 1 continues from task 1.3; finished tasks stay ticked.
jayjfletcher commentedon Oct 25, 2026
Ring Master factory resumed the build (run
wf_4b69ba3b-4de): group 1 is done, groups 2–8 are building now.jayjfletcher commentedon Oct 25, 2026
Ring Master: build restarted from group 2 after rework (worktree now installs every refactor-circus package from its local checkout with
composer local:install).jayjfletcher commentedon Oct 25, 2026
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.
jayjfletcher commentedon Oct 25, 2026
Ring Master: factory build resumed (2026-10-24) for groups 3–12; groups 1, 2 and 9 are already built.
jayjfletcher commentedon Oct 25, 2026
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.jayjfletcher commentedon Oct 25, 2026
Build resumed (Ring Master factory) after D-055: group 3 follow-up (throwing column check), then groups 4–8.
jayjfletcher commentedon Oct 25, 2026
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.
jayjfletcher commentedon Oct 25, 2026
Build resumed (factory, groups 6-8) after D-056.
jayjfletcher commentedon Oct 25, 2026
Decision D-057 (raised by build, answered in RingMaster, 2026-10-25)
Q: What should
DELETE cortex/servers/{server}/instructionsanddelete-server-instructionsanswer?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.jayjfletcher commentedon Oct 25, 2026
Build resumed after D-057 (instructions delete response): finishing group 6 (tasks 6.4–6.6), then groups 7 and 8, then review.
jayjfletcher commentedon Oct 25, 2026
Decision D-058 (answered in RingMaster, raised by build)
The ArchTest security-preset failure accepted locally in D-054 (
unserializein Atrium'sSearchRegistry.php:270, flagged becausecomposer local:installsymlinks Atrium outsidevendor/) will be fixed at the source: a separate Atrium job stopsSearchRegistryfrom usingunserialize(for example by passing search results as JSON). After that,composer local:updateruns in Cortex and the gate expectscomposer testfully green.This job's build is on hold until the Atrium fix lands.
jayjfletcher commentedon Oct 26, 2026
Ring Master: build resumed. Atrium's
SearchRegistryno longer usesunserialize(D-058), so the local ArchTest security-preset failure is gone; running the factory review rounds again.Merge pull request #10 from Refactor-Circus/ring-master/2026-10-23-19…