Agent configuration and MCP

Agent revision

Agent revisions pin configuration for each run. The service validates incoming payloads against the corresponding runtime schema.

type AgentRevision = {
  id: string;
  agent_id: string;
  revision: number;
  model_binding: string;       // opaque reference, never a credential
  instructions: string;
  tool_versions: Record<string, string>;
  grant_refs: string[];        // resolved and checked by the server
  service_budget_ref: string;
  execution_mandate_ref: string | null;
};

Revision pinning

A run references one immutable agent revision. Changing the model, brief or toolkit creates a new revision. Persistent task configuration pins strategy and calculation versions so an ongoing job cannot silently inherit edited instructions. Grant revocation remains dynamic even when the configuration is pinned.

An external agent retains its own runtime and memory. Seer returns authorized artifacts and operation references. The integration does not require copying the client’s entire conversational context or reasoning trace into Seer.

MCP discovery

MCP discovery uses tools/list. The examples below use protocol version 2025-06-18 and show the manifest and invocation for market history.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

A tool manifest returned by discovery

Discovery excerpt showing the input contract. The complete response also exposes outputSchema for the structured result envelope. HTTP discovery exposes outputSchema for the data payload, as described in Tool contracts.

{
  "name": "seer_market_bars",
  "description": "Retrieve completed daily listing observations.",
  "inputSchema": {
    "$ref": "#/$defs/MarketBarsInput",
    "type": "object",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$defs": {
      "MarketBarsInput": {
        "type": "object",
        "properties": {
          "instrumentId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "start": {
            "type": "string",
            "format": "date"
          },
          "end": {
            "type": "string",
            "format": "date"
          },
          "interval": {
            "type": "string",
            "enum": [
              "1d"
            ]
          },
          "adjustment": {
            "type": "string",
            "enum": [
              "split_only",
              "total_return",
              "none"
            ]
          },
          "as_of": {
            "type": "string",
            "format": "date-time"
          },
          "cursor": {
            "type": "string"
          }
        },
        "required": [
          "instrumentId"
        ],
        "additionalProperties": false,
        "description": "Defaults: 252 completed sessions ending at the latest eligible session, interval 1d, adjustment split_only, as_of invocation admission time. start/end, when supplied, are both required and are inclusive session dates; input/output coverage records actual bounds. Maximum 1000 sessions per page. Never returns a partial current-session bar.",
        "dependentRequired": {
          "start": [
            "end"
          ],
          "end": [
            "start"
          ]
        }
      }
    }
  }
}

MCP invocation

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "seer_market_bars",
    "arguments": {"instrumentId": "equity:listing:apple-common-xnas"}
  }
}

One domain boundary across transports

The MCP name seer_market_bars maps to the domain tool market.bars. HTTP discovery exposes the domain name, which is the tool field used in HTTP invocation. Both transports resolve the same argument schema, capability grants and source entitlements.

A protocol error describes an invalid protocol interaction. A tool-execution failure describes an admitted invocation that could not produce its result. Structured results retain provenance, coverage and warnings across transports; natural-language summaries are views of that record. MCP initialization negotiates the protocol version and the connection identity flow authenticates access.

Configuration immutability and dynamic authority

A configuration revision fixes the instructions, model binding and selected tool versions for reproducibility. Authority remains evaluated at invocation time. Revoking a grant therefore affects a pinned revision immediately; it does not require rewriting the historical configuration.

This separates two questions: what configuration produced a result, and what the principal may do now. Replaying a calculation can recover the former without restoring expired credentials or revoked financial permission.

Protocol errors and tool outcomes

Protocol reference

Connect over Streamable HTTP

Use the mcp_endpoint returned by GET /v1/connection. The connection binds its agent revision and tool grants server-side; tool arguments contain business inputs, not credentials or an arbitrary agent identity. Use the advertised protected-resource metadata and authorization server for an interactive MCP connection. Tokens are audience-bound to the MCP resource; do not reuse a REST token unless it was issued for that audience.

The examples pin MCP 2025-06-18. Initialize, verify the negotiated version, send notifications/initialized, then discover tools. Subsequent HTTP requests carry MCP-Protocol-Version and, when issued, Mcp-Session-Id. Accept both application/json and text/event-stream. A lost session is reinitialized without discarding durable Seer job or action identities.

Initialize the MCP session

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "seer-research-client",
      "version": "1.0.0"
    }
  }
}

Complete initialization

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

Structured output and asynchronous work

tools/call returns content plus structuredContent containing ToolResult or AcceptedJob. A text content item carries the same serialized result for clients that do not consume structuredContent. A protocol request ID identifies a message, not a durable business operation.

Read and compute tools are available through MCP. Background work is followed using seer_jobs_get and seer_artifacts_get. Financial submission is performed through the REST action lifecycle with an explicit idempotency key and action-bound authorization; a free-form MCP tool response cannot supply approval. MCP tools/list can paginate with nextCursor. The exposed manifests identify their output schemas and effect class.

Transport and authorization standards

Read an asynchronous MCP job

The session utility returns Job in structuredContent. When completed, call seer_artifacts_get with artifact_id=result_ref; its structuredContent is Artifact. Both utilities also return a serialized text content item. Their manifests are under mcp_utilities in tool-catalog.json, with jobs:read and artifacts:read scopes respectively. Unlike business tools, these utilities do not wrap the retrieved resource in another ToolResult.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "seer_jobs_get",
    "arguments": {
      "job_id": "job_example_1"
    }
  }
}