MCP Server

The @tangogroup/forge-mcp package is a Model Context Protocol (MCP) server that wraps the Forge Platform API. It exposes Forge capabilities as tools (for actions and queries) and resources (for reading state), letting AI agents interact with the platform through their native tool-use interface.

🤔 What is MCP?

The Model Context Protocol is an open standard for connecting AI agents to external tools and data sources. An MCP server declares the tools and resources it offers. An MCP client (typically an AI agent runtime) discovers those capabilities and invokes them as needed. The protocol handles parameter validation, error formatting, and result delivery. For Forge, this means an AI agent can list agents, query events, check health, deploy agents, and read budget status — all through the same interface it uses for any other tool.

📦 Installation

npm install @tangogroup/forge-mcp

⚙️ Configuration

The MCP server requires two environment variables:

Variable	Required	Description
`FORGE_API_URL`	Yes	Base URL of your Forge deployment (e.g., `https://forge.gloo.ai`)
`FORGE_API_KEY`	Yes	API key with scopes matching the tools you want to expose

Claude Desktop

Add the server to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["@tangogroup/forge-mcp"],
      "env": {
        "FORGE_API_URL": "https://forge.gloo.ai",
        "FORGE_API_KEY": "forge_sk_abc123..."
      }
    }
  }
}

Claude Code

Add the server to your project’s .claude/settings.json or user-level ~/.claude/settings.json:

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["@tangogroup/forge-mcp"],
      "env": {
        "FORGE_API_URL": "https://forge.gloo.ai",
        "FORGE_API_KEY": "forge_sk_abc123..."
      }
    }
  }
}

Direct Execution

Run the MCP server directly via the CLI binary:

export FORGE_API_URL="https://forge.gloo.ai"
export FORGE_API_KEY="forge_sk_abc123..."

npx @tangogroup/forge-mcp

The server communicates over stdio using the MCP standard transport.

The API key you provide determines which tools are functional. If the key lacks agents:write scope, deployment tools will return authorization errors. Grant the minimum scopes required for your use case.

💻 Programmatic Usage

You can also create the MCP server programmatically in your own application:

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { ForgePlatformClient, createForgeServer } from "@tangogroup/forge-mcp";

const client = new ForgePlatformClient(
  "https://forge.gloo.ai",
  process.env.FORGE_API_KEY!,
);

const server = createForgeServer(client);
const transport = new StdioServerTransport();

await server.connect(transport);

🔧 Tools

Tools are invocable actions that agents call to query or mutate Forge state. The server registers 17 tools across 9 domains.

Agents

Tool	Description	Parameters
`forge_list_agents`	List all agents registered on the platform	`gatewayId?`: filter by gateway
`forge_get_agent`	Get detailed information about a specific agent	`agentId`: the agent’s document ID
`forge_transition_agent_stage`	Transition an agent’s lifecycle stage (draft, active, suspended, archived)	`agentId`, `to`: target stage, `reason?`
`forge_get_agent_lifecycle_history`	Get lifecycle transition history for an agent	`agentId`, `limit?`: max transitions (1-100)

Deployment

Tool	Description	Parameters
`forge_deploy_agent`	Deploy an agent to a specific gateway	`agentId`, `gatewayId`, `overrides?`: config overrides
`forge_undeploy_agent`	Remove an agent deployment from a gateway	`agentId`, `gatewayId`

Runs

Tool	Description	Parameters
`forge_list_runs`	List workflow runs with optional filters	`runType?`, `limit?`: 1-100 (default 25)
`forge_get_run`	Get run detail including all steps	`runId`

Health

Tool	Description	Parameters
`forge_get_health`	Get platform and gateway health status	(none)

Events

Tool	Description	Parameters
`forge_query_events`	Query events with compound filters and pagination	`since` (ISO 8601 or Unix ms), `until?`, `category?`, `source?`, `severity?`, `agentId?`, `gatewayId?`, `runId?`, `interfaceId?`, `resourceType?`, `resourceId?`, `limit?`, `cursor?`
`forge_get_event_summary`	Get aggregated event counts by category, severity, and source	`since`, `until?`, `agentId?`, `gatewayId?`, `interfaceId?`

Models

Tool	Description	Parameters
`forge_list_models`	List all models in the model catalog	(none)
`forge_get_model`	Get details for a specific model	`modelId` (e.g., `anthropic/claude-sonnet-4-20250514`)

Skills

Tool	Description	Parameters
`forge_list_skills`	List all skills in the skill catalog	(none)
`forge_get_skill`	Get details for a specific skill	`skillId`

Workflows

Tool	Description	Parameters
`forge_list_workflows`	List all workflow definitions	(none)
`forge_get_workflow`	Get details for a specific workflow	`workflowId`: ID or name

Budgets

Tool	Description	Parameters
`forge_get_budget_status`	Get budget usage and remaining amounts across all scopes	(none)

📦 Resources

Resources are read-only data endpoints that agents can access to understand current platform state. They are simpler than tools — no parameters, just a URI that returns JSON.

Resource	URI	Description
`forge-agents`	`forge://agents`	All registered agents
`forge-agent`	`forge://agents/{agentId}`	A specific agent by ID (parameterized)
`forge-health`	`forge://health`	Current platform health status
`forge-events-recent`	`forge://events/recent`	Events from the last hour (up to 100)
`forge-events-summary`	`forge://events/summary`	Event summary for the last 24 hours
`forge-models`	`forge://models`	All models in the catalog
`forge-skills`	`forge://skills`	All skills in the catalog
`forge-budgets`	`forge://budgets`	Budget status across all scopes

Resources are useful for giving agents background context about the platform state without requiring explicit tool calls. MCP clients can preload resources when starting a conversation.

🤖 How Agents Use the MCP Server

When an MCP client connects to the Forge server, it receives the full list of available tools and resources. The agent then invokes them as needed during its reasoning loop.

Example: Agent Checks Health Before Deploying

An agent tasked with deploying a new agent version might:

Check platform health

The agent calls forge_get_health to verify all gateways are operational before attempting a deployment.

Review the agent definition

The agent calls forge_get_agent with the target agent ID to confirm the current lifecycle stage and configuration.

Check budget status

The agent calls forge_get_budget_status to ensure there is remaining budget for the deployment.

Deploy the agent

The agent calls forge_deploy_agent with the agent ID, target gateway, and any configuration overrides.

Verify deployment

The agent calls forge_list_agents filtered by gateway to confirm the deployment is live.

Example: Agent Investigates an Error

An agent tasked with diagnosing a workflow failure might:

Query recent errors

The agent calls forge_query_events with severity: ["error", "critical"] and a recent since timestamp.

Get the failed run

The agent calls forge_get_run with the run ID from the error event to inspect step-level detail.

Check the agent's state

The agent calls forge_get_agent and forge_get_agent_lifecycle_history to determine if the agent was recently transitioned or has known issues.

Get event summary

The agent calls forge_get_event_summary to understand if this is an isolated failure or part of a broader pattern.

🔑 Required Scopes by Tool

The API key provided to the MCP server must have the scopes required by the tools you want to use.

Tools	Required Scope
`forge_list_agents`, `forge_get_agent`, `forge_get_agent_lifecycle_history`	`agents:read`
`forge_transition_agent_stage`, `forge_deploy_agent`, `forge_undeploy_agent`	`agents:write`
`forge_list_runs`, `forge_get_run`	`runs:read`
`forge_query_events`, `forge_get_event_summary`	`events:read`
`forge_get_health`	`agents:read`
`forge_list_models`, `forge_get_model`	`models:read`
`forge_list_skills`, `forge_get_skill`	`skills:read`
`forge_list_workflows`, `forge_get_workflow`	`workflows:read`
`forge_get_budget_status`	`budgets:read`

For a read-only agent that monitors platform state, use a key with: agents:read, runs:read, events:read, models:read, skills:read, workflows:read, budgets:read.

❌ Error Handling

When a tool call fails (invalid parameters, authorization errors, network issues), the MCP server returns the error as a text content block with isError: true. The error message includes the HTTP status, error code, and description from the Platform API.

Forge API error (403 forbidden): API key lacks required scope 'agents:write'

Agents receive this as a tool-use error and can adjust their approach accordingly — for example, by informing the user that they lack permission to perform the requested action.

Start Here

Agents

Workflows

Governance

Observability

Operations

Factories & Chat

Architecture

Execution Flows

API Reference

SDK & MCP

🤔 What is MCP?

📦 Installation

⚙️ Configuration

Claude Desktop

Claude Code

Direct Execution

💻 Programmatic Usage

🔧 Tools

Agents

Deployment

Runs

Health

Events

Models

Skills

Workflows

Budgets

📦 Resources

🤖 How Agents Use the MCP Server

Example: Agent Checks Health Before Deploying

Example: Agent Investigates an Error

🔑 Required Scopes by Tool

❌ Error Handling

🚀 Next Steps

TypeScript SDK

API Reference

Start Here

Agents

Workflows

Governance

Observability

Operations

Factories & Chat

Architecture

Execution Flows

API Reference

SDK & MCP

​🤔 What is MCP?

​📦 Installation

​⚙️ Configuration

​Claude Desktop

​Claude Code

​Direct Execution

​💻 Programmatic Usage

​🔧 Tools

​Agents

​Deployment

​Runs

​Health

​Events

​Models

​Skills

​Workflows

​Budgets

​📦 Resources

​🤖 How Agents Use the MCP Server

​Example: Agent Checks Health Before Deploying

​Example: Agent Investigates an Error

​🔑 Required Scopes by Tool

​❌ Error Handling

​🚀 Next Steps

TypeScript SDK

API Reference

🤔 What is MCP?

📦 Installation

⚙️ Configuration

Claude Desktop

Claude Code

Direct Execution

💻 Programmatic Usage

🔧 Tools

Agents

Deployment

Runs

Health

Events

Models

Skills

Workflows

Budgets

📦 Resources

🤖 How Agents Use the MCP Server

Example: Agent Checks Health Before Deploying

Example: Agent Investigates an Error

🔑 Required Scopes by Tool

❌ Error Handling

🚀 Next Steps