Skip to content

mcp.md

Latest commit

 

History

History
93 lines (72 loc) · 2.52 KB

mcp.md

File metadata and controls

93 lines (72 loc) · 2.52 KB
Raw

Model Context Protocol (MCP) Guide

Protocol Version: MCP 2026-07-28 Runtime Milestone: v1.0.1

MARSHAL implements an authenticated Model Context Protocol (MCP 2026-07-28) server enabling remote orchestrators, agents, and IDE tools to interact with the MARSHAL control plane.

1. Authentication & Bearer Tokens

All MCP HTTP endpoints require Bearer authentication using high-entropy tokens generated by the MARSHAL control plane.

Generating a Token

marshal auth token create --name mcp-orchestrator

Output:

Created Token ID: TOKEN-e6eeb825c43740c7
Plaintext Token: marshal_token_6e86f061e255da6d5b075084e08c3ff7821002ad9d02b250bee90024ab0e63d0
(Keep this token secret; it will not be shown again)

Authorization Header

Include the token in all HTTP requests:

Authorization: Bearer $MARSHAL_TOKEN
Content-Type: application/json
Mcp-Method: tools/call

2. Running the MCP Server

Start Server

marshal mcp serve --listen 127.0.0.1:8080

Inspect Status

marshal mcp status

3. Supported MCP Methods & Tools

Method / Tool Description
server/discover Discovers available MCP capabilities and tool declarations
tools/list Returns list of exposed runtime tools
tools/call (task_run) Dispatches task execution to a provider adapter
tools/call (task_status) Queries status, leases, and revision metadata for a task
tools/call (task_claim) Claims a task lease for an agent
tools/call (task_release) Releases a task lease
tools/call (events_list) Fetches runtime audit events

4. Authenticated Request Example

curl -s -X POST http://127.0.0.1:8080/mcp \
  -H "Authorization: Bearer $MARSHAL_TOKEN" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: task_status" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "task_status",
      "arguments": {
        "task_id": "TASK-001"
      }
    }
  }'

5. Security & Policy Enforcement

MCP requests do not bypass MARSHAL security controls:

  • Token Verification: Requests missing or specifying invalid/revoked tokens receive HTTP 401 Unauthorized.
  • Policy Checks: Task execution requests are evaluated against CAPABILITIES.yaml.
  • Sandboxing: Provider adapters execute inside isolated Git worktrees and bubblewrap sandboxes.
  • Evidence Audit: All MCP tool calls are logged as immutable events in SQLite.