MCP / Agent Access

Forge MCP is the agent-facing execution gateway into Forge Pool.

It allows compatible AI agents to:

discover capabilities
construct execution payloads
run deterministic workloads
retrieve compact results
analyze distributions
replay executions

What MCP Is (and Is Not)

Forge MCP is not a chatbot integration.

It is not a data API.

It is:

A deterministic execution interface for probabilistic workloads.

Agents do not ask for answers.

Agents execute workloads.

Why MCP Matters

Most AI systems today operate on:

static data
probabilistic predictions

Forge MCP introduces a different model:

agents execute scenario spaces
outputs are distributions, not guesses
results are deterministic and replayable

This enables agents to:

reason over uncertainty
compare scenarios
produce auditable outputs

Endpoint

txt

POST https://api.forgepool.io/v1/mcp

Example Request

bash

curl -X POST https://api.forgepool.io/v1/mcp \
  -H "Authorization: Bearer fpak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "forge.capabilities.list",
    "input": {}
  }'

Authentication

Forge MCP uses the same authentication model as the Web Core API.

Supported

txt

Authorization: Bearer fpat_...

Personal tokens are supported, but may require:

a default project
or a single-project context

Tool Model

All interactions use a single endpoint with a tool selector:

json

{
  "tool": "forge.execute",
  "input": { ... }
}

Canonical Request Structure

All MCP requests use the same canonical structure:

json

{
  "tool": "forge.execute",
  "input": { ... }
}

Important:

always use tool
always use input
never use params
never invent capability identifiers
always use capability identifiers exactly as returned

Execution Flow

All agent interactions follow the same pattern:

discover → forge.capabilities.list
describe → forge.capability.describe
execute → forge.execute
retrieve → forge.run.result

This creates a closed execution loop for agents.

Available Tools (v0)

Discovery

forge.capabilities.list
forge.capability.describe

Execution

forge.execute

Inspection

forge.run.status
forge.run.result

Execution Lifecycle

1. Discover

json

{
  "tool": "forge.capabilities.list",
  "input": {}
}

2. Describe

json

{
  "tool": "forge.capability.describe",
  "input": {
    "capability_id": "forge.primitive.mc.v1"
  }
}

Returns:

schema
handler information
execution contract
validation requirements
example payloads
execution guidance

3. Execute

json

{
  "tool": "forge.execute",
  "input": {
    "payload": {
      "ctx": {
        "billing": {
          "mode": "test"
        }
      },
      "op": {
        "name": "mc",
        "version": 1,
        "profile": "insurance.loss.v1"
      },
      "policy": {
        "target": "cpu",
        "verify": "none",
        "min_agents": 1,
        "max_agents": 4
      },
      "args": {
        "iterations": 100000
      }
    }
  }
}

4. Retrieve Result

json

{
  "tool": "forge.run.result",
  "input": {
    "job_id": "01...",
    "format": "compact"
  }
}

Validation and Agent Adaptation

Forge Pool returns structured validation feedback.

Example:

json

{
  "error": {
    "code": "validation_error",
    "message": "The horizon_days field is required."
  }
}

Agents can use this information to:

inspect missing requirements
adapt execution payloads
retry safely
converge toward valid deterministic execution

This enables iterative execution refinement without manual intervention.

Result Structure (Compact)

json

{
  "summary": {
    "mean": ...,
    "p05": ...,
    "p50": ...,
    "p95": ...
  },
  "quantiles": {...},
  "histogram": {...},
  "metrics": {
    "agents_used": ...,
    "wall_ms": ...
  },
  "replay_token": {...}
}

Distribution Interpretation

Forge Pool workloads typically return probabilistic distributions.

Agents should analyze:

mean (expected value)
percentiles (risk bounds)
tail exposure
volatility
skew and asymmetry

The most important outcomes are often located in the tails of the distribution, not in the mean.

Key Properties

Distribution-first

Forge Pool returns distributions, not single values.

Deterministic execution

Every run:

has a seed
is reproducible
is auditable

Replay

Every result includes:

json

{
  "replay_token": {...}
}

This allows exact re-execution.

Why Replayability Matters

Replayability enables:

auditability
deterministic verification
scenario comparison
regulatory traceability
reproducible AI-assisted analysis

This is especially important for:

financial systems
insurance modeling
scientific workloads
critical infrastructure analysis

Traceability

Each run includes:

trace_id
request_id
execution metadata

What Makes Forge MCP Different

Capability	Traditional AI Tools	Forge MCP
Data access	Yes	Yes
Execution	No	Yes
Deterministic replay	No	Yes
Distribution outputs	Rare	Native
Auditability	Limited	Built-in
Scenario comparison	Manual	Native

Billing Model

Default MCP behavior:

json

"billing": {
  "mode": "test"
}

no cost
safe experimentation
limited scope

Production execution requires:

explicit permission
proper token scope

Safety Constraints

MCP enforces:

iteration limits
execution bounds
billing restrictions
payload validation

Agents cannot bypass:

execution policies
system constraints

Agent Behavior Model

Agents should:

Discover capabilities
Inspect schema
Build valid payloads
Execute safely
Analyze distributions

Agents should NOT:

guess schemas
request unbounded execution
treat outputs as single values

Recommended Agent Behavior

Forge-compatible agents should:

discover capabilities first
inspect execution contracts
execute with safe billing mode
interpret distributions, not single outputs
retry safely after validation feedback

Agents should avoid:

guessing schemas
assuming profile arguments
requesting unbounded workloads
treating mean values as complete outcomes

Example: Insurance Loss

Mean:

expected loss

P95:

worst-case exposure

Distribution:

tail behavior
skew
risk concentration

Enterprise Use Cases

Forge MCP is suitable for:

financial risk modeling
insurance loss simulation
infrastructure stress testing
scenario exploration systems
AI-assisted decision engines

It enables agents to produce outputs that are:

auditable
reproducible
traceable

Summary

Forge MCP transforms agents into:

execution clients
probabilistic analysts
deterministic auditors

Final Note

Traditional AI systems generate responses.

Forge Pool enables agents to execute uncertainty spaces directly.

This transforms agents from conversational systems into deterministic execution operators.

→ Agent Quickstart

MCP / Agent Access ​

What MCP Is (and Is Not) ​

Why MCP Matters ​

Endpoint ​

Example Request ​

Authentication ​

Recommended ​

Supported ​

Tool Model ​

Canonical Request Structure ​

Execution Flow ​

Available Tools (v0) ​

Discovery ​

Execution ​

Inspection ​

Execution Lifecycle ​

1. Discover ​

2. Describe ​

3. Execute ​

4. Retrieve Result ​

Validation and Agent Adaptation ​

Result Structure (Compact) ​

Distribution Interpretation ​

Key Properties ​

Distribution-first ​

Deterministic execution ​

Replay ​

Why Replayability Matters ​

Traceability ​

What Makes Forge MCP Different ​

Billing Model ​

Safety Constraints ​

Agent Behavior Model ​

Recommended Agent Behavior ​

Example: Insurance Loss ​

Enterprise Use Cases ​

Summary ​

Final Note ​

MCP / Agent Access

What MCP Is (and Is Not)

Why MCP Matters

Endpoint

Example Request

Authentication

Recommended

Supported

Tool Model

Canonical Request Structure

Execution Flow

Available Tools (v0)

Discovery

Execution

Inspection

Execution Lifecycle

1. Discover

2. Describe

3. Execute

4. Retrieve Result

Validation and Agent Adaptation

Result Structure (Compact)

Distribution Interpretation

Key Properties

Distribution-first

Deterministic execution

Replay

Why Replayability Matters

Traceability

What Makes Forge MCP Different

Billing Model

Safety Constraints

Agent Behavior Model

Recommended Agent Behavior

Example: Insurance Loss

Enterprise Use Cases

Summary

Final Note