Forge Pool

Appearance

Native MCP Server ​

Forge Pool exposes a native Model Context Protocol (MCP) server for AI agents.

The Forge MCP server allows compatible AI clients to connect directly to Forge Pool and operate as execution clients over probabilistic workloads.

Agents can:

  • discover available Forge capabilities
  • search capability surfaces
  • inspect execution contracts
  • construct valid execution payloads
  • run deterministic workloads
  • retrieve compact results
  • analyze distributions
  • preserve replay and audit metadata
  • assist with Studio-oriented orchestration flows

Forge MCP is not a chatbot interface.

It is an execution interface.

Agents do not ask Forge Pool for opinions.

Agents execute workloads.

Endpoint ​

Forge Pool exposes MCP over a hosted HTTP endpoint:

txt
https://api.forgepool.io/mcp

This endpoint is intended for MCP-compatible AI clients such as:

  • Cursor
  • Claude Desktop
  • Claude Code
  • Windsurf
  • VS Code MCP clients
  • custom MCP clients
  • enterprise agent runtimes

Authentication ​

Forge MCP uses bearer-token authentication.

Recommended token type:

txt
fpak_...

Project-scoped tokens are recommended for agent execution because they provide:

  • direct project routing
  • isolated execution context
  • safer billing boundaries
  • clearer audit ownership
  • deterministic project attribution

Use the token through the standard authorization header:

txt
Authorization: Bearer fpak_...

Most MCP clients allow this header to be configured in the local MCP server configuration.

Never paste Forge tokens into an AI chat message.

Tokens should live in local client configuration, environment variables, secret managers, or enterprise credential stores.

Native MCP vs Legacy Agent Gateway ​

Forge Pool previously exposed an agent gateway using the structure:

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

That legacy shape is still useful for direct HTTP integrations and internal agent runners.

The native MCP server uses standard MCP tool discovery and tool invocation instead.

For MCP-compatible clients, use:

txt
https://api.forgepool.io/mcp

Do not use the legacy /v1/mcp endpoint for native MCP client configuration.

What Forge MCP Is ​

Forge MCP is the agent-facing execution surface for Forge Pool.

It allows AI systems to operate against Forge's execution substrate through a stable tool interface.

Forge MCP exposes:

  • capability discovery
  • capability search
  • capability description
  • workload execution
  • run status inspection
  • result retrieval
  • Studio template discovery
  • Studio template description
  • Studio template import support

Every execution still flows through Forge Web Core, Forge Hub, and the distributed Agent Mesh.

MCP does not bypass Forge runtime semantics.

It does not bypass validation.

It does not bypass billing policy.

It does not bypass execution constraints.

What Forge MCP Is Not ​

Forge MCP is not:

  • a chatbot
  • a generic data API
  • a replacement for Forge Studio
  • a replacement for the Forge API
  • a prompt-to-answer wrapper
  • an uncontrolled execution backdoor
  • an advisory engine

Forge MCP exposes deterministic execution capability.

AI agents construct, execute, inspect, and interpret workloads.

Forge Pool remains the runtime authority.

Core Agent Workflow ​

Forge-compatible agents should follow this sequence:

txt
discover
↓
search
↓
describe
↓
execute
↓
retrieve
↓
analyze

In practice:

  1. List or search capabilities.
  2. Select the most relevant capability.
  3. Describe the capability before execution.
  4. Build a payload using the returned contract.
  5. Execute in test billing mode first.
  6. Retrieve compact results.
  7. Interpret the distribution.
  8. Preserve replay and trace metadata.

Agents should not guess payloads.

Agents should not invent capability identifiers.

Agents should not treat single summary values as complete outcomes.

Public MCP Tool Names ​

Forge MCP exposes tool names using MCP-safe identifiers.

Capability Discovery ​

txt
forge_capabilities_list
forge_capabilities_search
forge_capability_describe

Execution ​

txt
forge_execute

Run Inspection ​

txt
forge_run_status
forge_run_result

Studio-Oriented Tools ​

txt
forge_studio_templates_list
forge_studio_template_describe
forge_studio_template_import

These public MCP tool names are designed for compatibility with clients that restrict tool names to alphanumeric characters and underscores.

Internally, Forge may still map these names to canonical tool identifiers.

Agents should use the MCP-safe names shown above.

Tool Reference ​

forge_capabilities_list ​

Lists available Forge capabilities.

Use this when the agent needs a broad overview of the execution surface.

Typical usage:

json
{
  "limit": 25
}

The response may include:

  • capability identifiers
  • block identifiers
  • names
  • descriptions
  • categories
  • families
  • handler types
  • status
  • visibility
  • tags
  • operation metadata

Agents should use this for discovery, not execution.

Searches and filters the Forge capability registry.

Typical usage:

json
{
  "q": "insurance loss",
  "primitive": "mc",
  "limit": 5
}

Useful filters include:

json
{
  "q": "capital buffer",
  "domain": "finance",
  "primitive": "mc",
  "limit": 10
}

The search tool is the preferred entry point when the user asks for a specific domain, workload class, or profile type.

Examples:

  • insurance loss
  • capital stress
  • liquidity risk
  • climate scenario
  • graph propagation
  • media verification
  • portfolio simulation

forge_capability_describe ​

Describes one specific capability and returns its execution contract.

Typical usage:

json
{
  "capability_id": "forge.primitive.mc.v1.insurance.loss.v1"
}

The response may include:

  • canonical operation reference
  • profile
  • required arguments
  • optional arguments
  • validation rules
  • minimum valid arguments
  • example arguments
  • execution guidance
  • payload quality notes
  • common errors
  • replay behavior
  • pricing hints

Agents should always call forge_capability_describe before calling forge_execute.

forge_execute ​

Executes a Forge workload.

Typical input shape:

json
{
  "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
    }
  }
}

Agents should execute in test mode unless the user explicitly authorizes production execution.

json
{
  "ctx": {
    "billing": {
      "mode": "test"
    }
  }
}

Execution returns a job identifier and execution metadata.

forge_run_status ​

Fetches the current status of a Forge job.

Typical usage:

json
{
  "job_id": "01..."
}

The response may include:

  • status
  • operation key
  • pricing key
  • surface key
  • iteration count
  • timing metadata
  • billing metadata
  • error state

Use this for long-running or asynchronous workloads.

forge_run_result ​

Retrieves a Forge job result.

Typical usage:

json
{
  "job_id": "01...",
  "format": "compact"
}

Supported result formats:

txt
compact
full

Compact format is recommended for AI agents.

It is designed to return the result surface most useful for reasoning while avoiding excessive context use.

forge_studio_templates_list ​

Lists available Forge Studio workboard templates.

Typical usage:

json
{
  "limit": 20
}

This is useful when an agent is assisting with Studio orchestration, workboard creation, or repeatable analysis flows.

forge_studio_template_describe ​

Describes a specific Studio template.

Typical usage:

json
{
  "template_id": "capital-review"
}

Agents should inspect templates before suggesting modifications or imports.

forge_studio_template_import ​

Returns a Studio template graph for import.

Typical usage:

json
{
  "template_id": "capital-review"
}

This tool returns graph JSON for Studio-oriented workflows.

Agents should not replace or modify user workboards without explicit user approval.

Execution Payload Model ​

Forge execution payloads use a canonical structure.

json
{
  "payload": {
    "ctx": {},
    "op": {},
    "policy": {},
    "args": {}
  }
}

ctx ​

Execution context.

Common fields:

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

op ​

Operation reference.

Example:

json
{
  "name": "mc",
  "version": 1,
  "profile": "insurance.loss.v1"
}

policy ​

Execution policy.

Example:

json
{
  "target": "cpu",
  "verify": "none",
  "min_agents": 1,
  "max_agents": 4
}

args ​

Profile-specific execution arguments.

These must be built from the capability description.

Do not guess these fields.

Use:

  • minimum_valid_args
  • example_args
  • args_required
  • args_optional
  • args_rules
  • agent_guidance

when available.

User request:

txt
Find insurance loss simulation capabilities.

Agent should call:

json
{
  "q": "insurance loss",
  "primitive": "mc",
  "limit": 5
}

Expected next step:

txt
Describe the most relevant direct forge_execute capability before building a payload.

Example: Capability Description ​

After search returns a capability such as:

txt
forge.primitive.mc.v1.insurance.loss.v1

Agent should call:

json
{
  "capability_id": "forge.primitive.mc.v1.insurance.loss.v1"
}

Then the agent should construct a payload only from the returned execution contract.

Example: Test-Mode Execution ​

A minimal execution pattern:

json
{
  "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
    }
  }
}

This is only an example.

Different profiles require different arguments.

Always inspect the capability contract first.

Result Structure ​

Compact results typically include:

  • execution status
  • operation reference
  • output summary
  • quantiles
  • histograms
  • metrics
  • replay metadata
  • billing metadata
  • trace identifiers

A compact result may contain:

json
{
  "output": {
    "summary": {},
    "quantiles": {},
    "histogram": {},
    "replay_token": {}
  },
  "metrics": {},
  "ctx": {
    "trace_id": "...",
    "request_id": "..."
  }
}

Agents should preserve:

  • job_id
  • trace_id
  • request_id
  • replay_token

These are part of the evidence surface.

Distribution Interpretation ​

Forge Pool returns distributions, not single predictions.

Agents should interpret:

  • mean
  • median
  • P05 / P50 / P95 / P99
  • tail behavior
  • skew
  • volatility
  • uncertainty spread
  • threshold exceedance
  • sensitivity to assumptions
  • replay metadata

The mean is not the answer.

The tails often contain the most important signal.

Replayability ​

Forge workloads are designed to be replayable.

Replayability enables:

  • auditability
  • deterministic verification
  • scenario comparison
  • governance review
  • regulatory traceability
  • debugging
  • reproducible analysis

Agents should treat replay metadata as first-class output.

When summarizing results, include whether replay metadata was returned.

Billing Model ​

Forge MCP defaults to safe execution patterns.

Recommended default:

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

Production execution requires explicit authorization.

Agents should not switch from test mode to production mode unless the user explicitly requests it.

Agents should also avoid unnecessarily large iteration counts during initial exploration.

Recommended flow:

  1. Start with a small test run.
  2. Inspect result shape.
  3. Increase iterations only when needed.
  4. Preserve replay metadata.
  5. Explain cost or billing implications if production execution is requested.

Safety Constraints ​

Forge MCP enforces:

  • authentication
  • token scope
  • execution validation
  • iteration limits
  • billing controls
  • payload validation
  • project routing
  • result size limits

Agents cannot bypass Forge execution policy by calling MCP.

Invalid payloads return structured error responses.

Agents should use these errors to self-correct.

Agent Self-Correction ​

Forge returns structured validation feedback.

Example:

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

Agents should respond by:

  1. Reading the error.
  2. Revisiting the capability contract.
  3. Adding missing fields.
  4. Retrying with a safe payload.
  5. Explaining the change to the user.

Agents should not repeatedly retry with guessed fields.

Agents should:

  • use forge_capabilities_search before choosing a capability
  • use forge_capability_describe before execution
  • build payloads from declared contracts
  • execute in test mode first
  • retrieve compact results
  • analyze distributions rather than single values
  • preserve replay metadata
  • explain uncertainty clearly
  • ask for user approval before production execution
  • avoid unnecessary large runs

Agents should not:

  • invent capability IDs
  • guess profile arguments
  • skip capability description
  • request unbounded execution
  • treat the mean as the full result
  • suppress uncertainty
  • hide validation errors
  • execute production workloads without approval
  • modify Studio workboards without user confirmation

Studio-Oriented Orchestration ​

Forge MCP can expose Studio-oriented surfaces to compatible agents.

This allows agents to assist with:

  • template discovery
  • graph inspection
  • workboard composition
  • replay-aware orchestration
  • execution flow preparation
  • artifact interpretation

Studio tools are intended for orchestration assistance.

The runtime remains authoritative.

Agents may help create or adapt Studio graphs, but they should not bypass validation or overwrite user work without explicit approval.

Enterprise Usage Pattern ​

A typical enterprise agent workflow looks like this:

txt
User asks risk question
↓
Agent searches Forge capabilities
↓
Agent describes selected capability
↓
Agent builds test-mode payload
↓
Agent asks user to approve execution if needed
↓
Forge executes workload
↓
Agent retrieves compact result
↓
Agent interprets distribution and tail risk
↓
Agent preserves replay metadata
↓
User receives evidence-backed analysis

Forge MCP is designed for organizations that need AI-assisted execution with:

  • governance
  • auditability
  • replay
  • uncertainty visibility
  • deterministic workload semantics

Example Prompts ​

Capability Discovery ​

txt
Use Forge MCP.

Search for insurance loss Monte Carlo capabilities.
Return the five most relevant direct execution capabilities.
Do not execute anything yet.

Capability Description ​

txt
Use Forge MCP.

Describe the most relevant insurance loss capability.
Summarize required arguments, optional arguments, and the minimum valid payload.
Do not execute yet.

Safe Test Execution ​

txt
Use Forge MCP.

Execute the described capability in test billing mode with a safe iteration count.
Then fetch compact results and summarize mean, P50, P95, tail behavior, and replay metadata.

Finance Scenario ​

txt
Use Forge MCP.

Search for capital buffer stress capabilities in the finance domain.
Describe the most relevant Monte Carlo capability.
Build a test-mode payload and wait for approval before execution.

Graph Propagation Scenario ​

txt
Use Forge MCP.

Search for graph propagation capabilities related to financial contagion.
Describe the most relevant graph capability.
Explain what inputs are required before execution.

Client Configuration ​

Most MCP clients require:

  • server name
  • MCP endpoint URL
  • authorization header

Generic configuration shape:

json
{
  "mcpServers": {
    "forge": {
      "url": "https://api.forgepool.io/mcp",
      "headers": {
        "Authorization": "Bearer fpak_..."
      }
    }
  }
}

Client-specific setup guides:

Troubleshooting ​

The client connects but no tools appear ​

Check that:

  • the MCP endpoint is correct
  • the client supports remote MCP servers
  • the authorization header is configured
  • the client was restarted after configuration
  • tools are enabled in the client UI

Endpoint should be:

txt
https://api.forgepool.io/mcp

The client shows authentication errors ​

Check that:

  • the token begins with fpak_
  • the token has not expired
  • the token is project-scoped
  • the token is included as a bearer token
  • there are no extra spaces in the header

Correct format:

txt
Authorization: Bearer fpak_...

The agent tries to inspect local files instead of using MCP ​

Some AI clients expose different tool surfaces across modes.

Use the client mode that supports MCP tool invocation.

In Cursor, use the standard Agent chat with MCP tools enabled.

The agent guesses payload fields ​

Tell the agent:

txt
Use forge_capability_describe before building the payload. Do not guess profile-specific fields.

The result is too large ​

Request compact result format:

json
{
  "job_id": "01...",
  "format": "compact"
}

The execution fails validation ​

Ask the agent to inspect the returned error and re-check the capability description.

Validation errors are intended to help agents converge toward valid execution.

Security Notes ​

Treat Forge tokens as secrets.

Do not paste tokens into chat prompts.

Do not commit tokens to repositories.

Prefer project-scoped tokens for agent execution.

Rotate tokens regularly.

Use separate tokens for:

  • local development
  • demos
  • production agents
  • enterprise environments

Revoke tokens that are exposed accidentally.

Summary ​

Forge MCP transforms AI agents into deterministic execution operators.

Through the native MCP server, agents can:

  • discover capabilities
  • inspect contracts
  • execute workloads
  • retrieve results
  • analyze distributions
  • preserve replay evidence
  • assist with Studio orchestration

Traditional AI systems generate responses.

Forge-connected agents execute uncertainty spaces.

That is the difference.

Next ​

Start with the agent quickstart:

→ Agent Quickstart

Or configure a specific client:

→ Cursor → Claude Desktop → Claude Code → Windsurf → VS Code

Deterministic execution infrastructure for distributed compute.

Copyright © 2026 Forge Pool