MCP Server Policy

Fragment policy MCP Server Policy

tags

agent

Connection

The StarSpec MCP server must be reachable before any work begins. The endpoint is:

http://localhost:3000/mcp        ← MCP (Streamable HTTP transport)
http://localhost:3000/mcp/health ← health check

If the client requires explicit MCP configuration, use:

{
  "mcpServers": {
    "starspec": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

The server uses Streamable HTTP transport. Clients that only support SSE or stdio will fail during tool discovery — this is a client configuration issue, not a server error.

Error handling cascade: MCP → Disk → Stop

Every get_instructions() call follows a two-step cascade:

MCP call
  ├─ success → use result, continue
  └─ failure → try disk fallback
       ├─ file exists → use result, log warning, continue
       └─ file missing → STOP. Report both failures. Do not improvise.

Key rule: the agent never fabricates content. It either gets authoritative content (from MCP or disk) or it stops.

Path mapping convention

Every get_instructions() path maps deterministically to a file path. Strip the starspec/ prefix, append .mdoc, and read from the instructions/ directory relative to the project root:

get_instructions("starspec/fragments/tags/inventory")
  → instructions/fragments/tags/inventory.mdoc

get_instructions("starspec/help")
  → instructions/help.mdoc

get_instructions("starspec/architecture")
  → instructions/architecture.mdoc

get_document has no disk fallback

Documents are content files created by the user at runtime-resolved paths. There is no predictable disk location to fall back to. When get_document fails, stop and flag a missing dependency — the document must be created first.

Fail-early rules

Situation	Action
MCP server unreachable at startup	Log warning. Switch to disk fallback for all subsequent fetches in this session.
get_instructions returns not found	Try disk at instructions/{path}.mdoc. If missing: stop, report the path.
get_document returns not found	Stop. Flag as missing dependency. No disk fallback.
Disk fallback file not found	Stop. Report both the MCP error and the missing file path. Do not improvise.
Any MCP tool call returns isError: true	Try disk fallback for get_instructions. If disk also fails: stop, report verbatim.

Never improvise when both MCP and disk fail. The instructions and documents are the ground truth. An agent operating without them will produce incorrect output.

requires: failure semantics

The MCP → disk → stop cascade applies uniformly to all fetches — boot, task routing, and workflow dependencies. When an agent loads a workflow fragment and iterates its requires: list, each fetch follows the same cascade. If any required dependency cannot be loaded from either source, the agent stops before executing the workflow — not mid-workflow.

Workflow loaded → read requires: [A, B, C]
  fetch A → ok
  fetch B → MCP fail → disk fail → STOP
  (C is never attempted)

Partial context is worse than no context. Fail-fast at the dependency level.

Verification

Before starting a task, verify the server is up:

get_instructions("starspec/help")

If this call succeeds, the server is reachable and the instruction index is available. If it fails, switch to disk fallback and log the warning before continuing.