Claude Desktop Integration

Claude Desktop can connect directly to Forge Pool through the native MCP server.

Once connected, Claude can:

• discover Forge capabilities
• inspect execution contracts
• execute deterministic workloads
• retrieve compact results
• analyze uncertainty distributions
• preserve replay metadata
• assist with Studio-oriented orchestration

Claude becomes an execution client rather than a pure conversational assistant.

---

Requirements

Before connecting Claude Desktop, ensure you have:

• a Forge Pool account
• a project
• a project-scoped token
• a recent Claude Desktop installation with MCP support

Recommended token type:

fpak_...

Project-scoped tokens provide:

• isolated execution context
• project-level attribution
• safer billing boundaries
• cleaner governance controls
• simpler credential management

---

MCP Endpoint

Forge Pool MCP endpoint:

https://api.forgepool.io/mcp

Authentication:

Authorization: Bearer fpak_...

---

Configuration Overview

Claude Desktop loads MCP servers from its local MCP configuration.

The exact configuration location depends on the operating system.

---

Configuration File Locations

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

The exact location may vary by Claude Desktop version. Refer to Anthropic documentation if the file is not present.

---

Add Forge MCP

Add Forge to the MCP server list.

Example:

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

Replace:

fpak_...

with your project token.

---

Restart Claude Desktop

After updating the configuration:

1. Save the file.
2. Fully quit Claude Desktop.
3. Reopen Claude Desktop.

MCP servers are loaded during startup.

---

Verify Connection

Ask Claude:

What MCP tools are available?

You should see Forge tools such as:

forge_capabilities_list
forge_capabilities_search
forge_capability_describe

forge_execute
forge_run_status
forge_run_result

If these tools appear, Claude is connected successfully.

---

First Discovery Workflow

Ask Claude:

Use Forge MCP.

Search for Monte Carlo capabilities related to insurance loss.
Do not execute anything yet.

Expected MCP tool:

forge_capabilities_search

This confirms that Claude can invoke Forge tools successfully.

---

Capability Inspection Workflow

After identifying a capability:

Use Forge MCP.

Describe the most relevant capability.
Summarize required arguments and provide a minimum valid payload.
Do not execute yet.

Expected MCP tool:

forge_capability_describe

Claude should inspect contracts before constructing payloads.

---

Safe Execution Workflow

After reviewing the capability contract:

Use Forge MCP.

Build a valid payload.
Execute in test mode.
Retrieve compact results.

Expected tools:

forge_execute
forge_run_result

Recommended billing mode:

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

---

Example End-to-End Prompt

Use Forge MCP.

1. Search for insurance loss Monte Carlo capabilities.
2. Select the most relevant direct execution capability.
3. Describe the capability.
4. Build a minimum valid payload.
5. Execute in test mode.
6. Retrieve compact results.
7. Summarize expected value, uncertainty, tail risk, and replay metadata.

---

Understanding Forge Results

Forge returns distributions rather than single outputs.

Claude should focus on:

• expected value
• median
• P05
• P50
• P95
• P99
• uncertainty spread
• tail behavior
• scenario sensitivity
• replay metadata

The average is only one part of the result surface.

---

Replay Metadata

Many Forge workloads return replay-aware metadata.

Claude should preserve:

• job_id
• trace_id
• request_id
• replay tokens
• execution identifiers

Replay metadata enables:

• auditability
• deterministic verification
• governance review
• scenario comparison
• reproducible analysis

---

Studio-Oriented Workflows

Forge MCP may expose Studio-oriented orchestration tools.

These allow Claude to:

• discover templates
• inspect workboards
• analyze execution graphs
• assist orchestration planning
• prepare Studio imports

Agents assist orchestration.

The Forge runtime remains authoritative.

---

Recommended Usage Pattern

Claude performs best when following:

search
↓
describe
↓
build
↓
execute
↓
retrieve
↓
analyze

This minimizes invalid payloads and improves execution reliability.

---

Security Recommendations

Use project-scoped tokens.

Do not:

• paste tokens into prompts
• commit tokens to source control
• share tokens across environments

Recommended:

• development tokens
• staging tokens
• production tokens
• periodic token rotation

Immediately revoke exposed tokens.

---

Troubleshooting

Forge Does Not Appear

Check:

• MCP configuration file location
• JSON validity
• Claude Desktop version
• full application restart

---

MCP Tools Are Missing

Verify:

https://api.forgepool.io/mcp

and:

Authorization: Bearer fpak_...

Check for:

• invalid token
• expired token
• malformed JSON

---

Authentication Errors

Ensure the header format is:

Authorization: Bearer fpak_...

and that the token is active.

---

Claude Guesses Payload Fields

Ask Claude:

Use forge_capability_describe before building the payload.
Do not invent profile-specific arguments.

The capability contract is the source of truth.

---

Results Are Too Large

Request compact results:

Retrieve compact results only.

or:

{
  "format": "compact"
}

---

Best Practices

Claude should:

• search before execution
• inspect contracts before payload construction
• execute in test mode first
• preserve replay metadata
• analyze distributions
• explain uncertainty explicitly

Claude should not:

• invent capability IDs
• guess arguments
• skip capability inspection
• suppress validation feedback
• execute production workloads without approval

---

Next

Learn the Forge MCP architecture:

→ Native MCP Server

Continue with:

→ Claude Code

Or return to:

→ Agent Quickstart