forge-mcp

This package gives coding agents access to current Amigo Agent Forge operations: managing org credentials, reading and mutating entity configurations, running conversation tests, and working with version sets from Claude Code, Codex, Cursor, and other MCP clients.

Prototype status

@amigo-ai/forge-tools is an experimental product under active development. Expect rough edges, changing tool contracts, and a faster-moving surface than a locked production SDK. Use it for evaluation and early workflows, not as a long-term stability guarantee.

Prototype Context

Forge MCP is the agent-facing bridge for current Agent Forge workflows. It is useful when a coding agent needs an MCP surface for org switching, entity CRUD, conversation simulation, and version-set operations.

For direct typed application integrations against the Platform API, use @amigo-ai/platform-sdk.

Related MCP server: hivegate

Documentation

Installation

Add the server to your MCP configuration.

Via npm

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["-y", "@amigo-ai/forge-tools"]
    }
  }
}

From GitHub

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["-y", "github:amigo-ai/forge-mcp"]
    }
  }
}

From a local clone

git clone git@github.com:amigo-ai/forge-mcp.git
cd forge-mcp
npm install
npm run build

{
  "mcpServers": {
    "forge": {
      "command": "node",
      "args": ["/absolute/path/to/forge-mcp/dist/index.js"]
    }
  }
}

Credentials

Credentials are stored per org in ~/.amigo/credentials/{org_id}.json.

Recommended flow

Start the server without environment variables, then ask your coding agent to add org credentials:

Use forge_add_org to add credentials for org "acme"
Use forge_add_org to add credentials for org "acme-staging"

The tool validates credentials by signing in before saving them.

Bootstrap with environment variables

You can bootstrap one org on startup:

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["-y", "@amigo-ai/forge-tools"],
      "env": {
        "AMIGO_ORG_ID": "your-org",
        "AMIGO_API_KEY": "your-api-key",
        "AMIGO_API_KEY_ID": "your-api-key-id",
        "AMIGO_USER_ID": "your-user-id"
      }
    }
  }
}

What your agent can do

• Add, remove, list, and switch active org credentials

• Create, update, read, list, and delete Agent Forge entity types

• Run smoke tests and multi-turn simulations

• Inspect conversation insights and evaluations

• Manage version sets and rollbacks

Multi-org support

All tools accept an optional org_id. Resolution order is:

1. Explicit org_id on the tool call

2. Session org set by forge_set_org

3. Default org in ~/.amigo/config.json

Tool catalog

Org management

Entity CRUD

Supported entity types: agent, context_graph, service, dynamic_behavior_set, tool, persona, scenario, metric, unit_test, unit_test_set, user_dimension

Conversation testing

Version management

MCP Resources

• amigo://instructions for Agent Forge guidance

• amigo://dependency-order for entity dependency ordering

Environment Variables

All variables are optional and only apply to startup bootstrap:

Development

npm install
npm run build
npm run lint
npm test