Windsurf Integration

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

Once connected, Windsurf agents can:

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

Forge MCP allows Windsurf to operate as an execution client over uncertainty-aware workloads rather than a traditional code assistant.

---

Requirements

Before connecting Windsurf, ensure you have:

• a Forge Pool account
• a project
• a project-scoped token
• a Windsurf installation with MCP support enabled

Recommended token type:

fpak_...

Project-scoped tokens provide:

• isolated execution context
• deterministic routing
• cleaner governance boundaries
• project-level attribution
• safer billing management

---

MCP Endpoint

Forge Pool MCP endpoint:

https://api.forgepool.io/mcp

Authentication:

Authorization: Bearer fpak_...

---

Configure Windsurf

Add Forge MCP to your Windsurf MCP configuration.

Example:

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

Replace the example token with your project-scoped token.

---

Restart Windsurf

After configuration:

1. Save the configuration.
2. Fully restart Windsurf.
3. Reopen the workspace.

Most MCP clients load MCP server configuration during startup.

---

Verify Connection

Ask Windsurf:

Use Forge MCP.

List available Forge tools.

Expected Forge tools:

forge_capabilities_list
forge_capabilities_search
forge_capability_describe

forge_execute
forge_run_status
forge_run_result

If these tools appear, Forge MCP is connected successfully.

---

Discovery Workflow

Recommended first prompt:

Use Forge MCP.

Search for insurance loss Monte Carlo capabilities.

Do not execute anything.

Expected tool:

forge_capabilities_search

---

Contract Inspection Workflow

After selecting a capability:

Use Forge MCP.

Describe the capability.

Provide required arguments and a minimum valid payload.

Do not execute.

Expected tool:

forge_capability_describe

Agents should inspect execution contracts before building payloads.

---

Safe Execution Workflow

Once the contract has been inspected:

Use Forge MCP.

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 catastrophe loss capabilities.
2. Select the most relevant 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 Results

Forge returns distributions rather than single outputs.

Windsurf should focus on:

• expected value
• median
• percentiles
• uncertainty spread
• tail behavior
• replay metadata

The average alone rarely tells the complete story.

---

Replay Metadata

Agents should preserve:

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

Replay metadata enables:

• deterministic verification
• governance review
• auditability
• scenario comparison

---

Studio-Oriented Workflows

Forge MCP may expose Studio-oriented tools.

These allow Windsurf to:

• discover templates
• inspect orchestration graphs
• assist workboard design
• prepare template imports
• review execution structure

Agents assist orchestration.

The Forge runtime remains authoritative.

---

Security Recommendations

Use project-scoped tokens.

Do not:

• commit tokens
• paste tokens into prompts
• reuse production credentials across environments

Recommended:

• separate development tokens
• separate production tokens
• periodic token rotation

---

Troubleshooting

Forge Tools Do Not Appear

Verify:

https://api.forgepool.io/mcp

and:

Authorization: Bearer fpak_...

Restart Windsurf after configuration changes.

---

Authentication Errors

Check:

• token validity
• token scope
• authorization header formatting
• token expiration

---

Invalid Payload Construction

Ask Windsurf:

Use forge_capability_describe before constructing payloads.
Do not guess profile-specific arguments.

The capability contract is authoritative.

---

Best Practices

Windsurf should:

• search before execution
• inspect contracts before building payloads
• execute in test mode first
• preserve replay metadata
• analyze distributions explicitly

Windsurf should not:

• invent capability identifiers
• guess arguments
• skip contract inspection
• suppress replay metadata
• execute production workloads without approval

---

Next

Learn the MCP architecture:

→ Native MCP Server

Continue with:

→ VS Code

Or return to:

→ Agent Quickstart