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.

Documentation

Need	Best entry point
Product and platform docs	docs.amigo.ai
Prototype repo issues and feedback	GitHub Issues
Contributor guidance	CONTRIBUTING.md
Security reporting	SECURITY.md

Installation

Requires Node.js 18 or newer; development and CI use Node.js 22. This prototype uses Classic API organization credentials at api.amigo.ai; Platform workspace keys are not interchangeable. Start with a designated test organization because its tools can create, update, and delete configuration.

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 https://github.com/amigo-ai/forge-mcp.git
cd forge-mcp
npm ci
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

Tool	Description
forge_set_org	Set the active org for the session
forge_list_orgs	List configured orgs with auth status
forge_add_org	Add or update credentials for an org
forge_remove_org	Remove stored credentials

Entity CRUD

Tool	Description
forge_entity_list	List entities of a type
forge_entity_get	Get full entity details
forge_entity_create	Create a new entity
forge_entity_update	Update an entity
forge_entity_delete	Delete an entity

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

Conversation testing

Tool	Description
forge_smoke_test	Quick single-turn test against a service
forge_simulate	Multi-turn automated simulation
forge_conversation_insights	Inspect state transitions and memory
forge_conversation_evaluate	Run on-demand metric evaluation

Version management

Tool	Description
forge_version_set_list	List version sets for a service
forge_version_set_upsert	Create or update a version set
forge_version_set_promote	Promote one version set to another
forge_version_rollback	Roll back an entity to a previous version

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:

Variable	Description
AMIGO_ORG_ID	Org to bootstrap and set as session default
AMIGO_API_KEY	API key for the bootstrapped org
AMIGO_API_KEY_ID	API key identifier
AMIGO_USER_ID	User ID
AMIGO_API_BASE_URL	API base URL. Defaults to https://api.amigo.ai
FORGE_LOG_LEVEL	Log verbosity: debug, info, warn, error

Development

npm ci
npm run build
npm run lint
npm test