Skip to main content
Glama
Sign In
forge-mcp

forge-mcp

by concurrence-hq
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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.

Forge MCP prototype architecture

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

Related MCP server: @restforge-dev/mcp-server

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

Available Tools

37 tools
forge_add_orgA

Add or update credentials for an org. Validates the credentials by signing in.

Inputs: org_id (required), api_key (required), user_id (required), api_key_id (required), +2 more.

forge_agent_createC

Create a new agent.

Inputs: agent_name (required), org_id.

forge_agent_updateA

Update an agent by creating a new version. The initial version requires: initials, identity, background, behaviors, and communication_patterns. Subsequent versions can include only changed fields. Do NOT include agent_name, greeting, dynamic_behavior_set_ids, user_dimension_ids, or persona_ids.

Inputs: agent_id (required), org_id, identity, initials, +4 more.

forge_context_graph_createB

Create a new context graph (state machine that defines conversation flow).

Inputs: state_machine_name (required), org_id.

forge_context_graph_updateB

Update a context graph by creating a new version. All fields are required. The terminal state must have exactly one action.

Inputs: states (required), description (required), terminal_state (required), context_graph_id (required), +7 more.

forge_conversation_evaluateC

Run on-demand metric evaluation against a conversation.

Inputs: metric_name (required), conversation_id (required), org_id, interaction_id.

forge_conversation_insightsB

Get debugging insights for a conversation, including state transitions and triggered behaviors.

Inputs: conversation_id (required), org_id, interaction_id.

forge_dynamic_behavior_set_createB

Create a new dynamic behavior set (runtime instructions injected based on triggers).

Inputs: name (required), tags (required), initial_version (required), applied_to_services (required), +1 more.

forge_dynamic_behavior_set_updateB

Update dynamic behavior set metadata. Only provided fields are changed.

Inputs: dynamic_behavior_set_id (required), name, tags, org_id, +2 more.

forge_entity_createC

Create a new entity of the given type. Provide the entity data as a JSON string or object.

Inputs: data (required), entity_type (required), org_id.

forge_entity_deleteA

Delete an entity. This is irreversible.

Inputs: entity_id (required), entity_type (required), org_id.

forge_entity_getA

Get the full details of a specific entity by ID. Returns the latest version.

Inputs: entity_id (required), entity_type (required), org_id.

forge_entity_listB

List all entities of a given type in an org.

Inputs: entity_type (required), org_id.

forge_entity_updateB

Update an existing entity by creating a new version. Provide the full version data.

Inputs: data (required), entity_id (required), entity_type (required), org_id.

forge_list_orgsA

List all configured orgs with their auth status and show the current session/default org.

Inputs: no named parameters.

forge_metric_createC

Create a new metric for evaluating conversations.

Inputs: name (required), tags (required), description (required), metric_value (required), +3 more.

forge_metric_updateC

Update a metric. Only provided fields are changed.

Inputs: metric_id (required), tags, org_id, description, +2 more.

forge_persona_createC

Create a new simulation persona with its initial version.

Inputs: name (required), role (required), tags (required), initial_version (required), +1 more.

forge_persona_updateA

Update persona metadata (tags). Use forge_entity_update for version changes.

Inputs: persona_id (required), tags, org_id.

forge_remove_orgB

Remove stored credentials for an org.

Inputs: org_id (required).

forge_scenario_createA

Create a new simulation scenario with its initial version.

Inputs: name (required), tags (required), initial_version (required), org_id.

forge_scenario_updateA

Update scenario metadata (tags). Use forge_entity_update for version changes.

Inputs: scenario_id (required), tags, org_id.

forge_service_createA

Create a new service linking an agent and context graph into a deployable unit. IMPORTANT: Both the agent and context graph must already have at least one version before creating the service.

Inputs: name (required), tags (required), agent_id (required), keyterms (required), +4 more.

forge_service_updateB

Update an existing service. Only provided fields are changed.

Inputs: service_id (required), name, tags, org_id, +5 more.

forge_set_orgA

Set the active org for this session. Subsequent tool calls will use this org by default.

Inputs: org_id (required), set_as_default.

forge_simulateC

Run an automated multi-turn conversation simulation against a service.

Inputs: service_name (required), org_id, max_turns, version_set, +1 more.

forge_smoke_testA

Run a quick smoke test against a service. Creates a conversation, sends a message, and returns the agent's response.

Inputs: service_name (required), org_id, message, version_set.

forge_tool_createB

Create a new tool (external action the agent can invoke).

Inputs: name (required), tags (required), description (required), org_id.

forge_tool_updateA

Update tool metadata (description and tags). Tool versions are published separately.

Inputs: tool_id (required), tags, org_id, description.

forge_unit_test_createB

Create a new simulation unit test.

Inputs: name (required), tags (required), persona_id (required), service_id (required), +6 more.

forge_unit_test_set_createB

Create a new unit test set (collection of unit tests to run together).

Inputs: name (required), tags (required), description (required), unit_test_runs (required), +1 more.

forge_unit_test_set_updateA

Update a unit test set. Only provided fields are changed.

Inputs: unit_test_set_id (required), name, tags, org_id, +2 more.

forge_unit_test_updateB

Update a unit test. Only provided fields are changed.

Inputs: unit_test_id (required), tags, org_id, run_count, +7 more.

forge_version_rollbackB

Roll back an entity to a previous version. Lists available versions for selection.

Inputs: entity_id (required), entity_type (required), version_number (required), org_id.

forge_version_set_listB

List all version sets for a service, showing pinned versions.

Inputs: service_name (required), org_id.

forge_version_set_promoteB

Promote one version set to another (e.g. preview -> release).

Inputs: source (required), target (required), service_name (required), org_id.

forge_version_set_upsertA

Create or update a version set for a service. Use latest=true to pin to the current latest versions.

Inputs: set_name (required), service_name (required), latest, org_id, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    C2.9/5.0

    Scored across 37 tools

    Disambiguation2/5

    Many entity-specific create/update tools (agent, context_graph, metric, etc.) overlap with the generic forge_entity_create/forge_entity_update, and the update semantics are inconsistent: some entity-specific updates create versions, others only edit metadata while pointing to forge_entity_update for version changes. This creates real ambiguity about which tool to call for a given change.

    Naming Consistency4/5

    Most tools follow forge_<entity>_<action>, and all use snake_case, but org tools flip to forge_<action>_<entity> (list_orgs, set_org) and a couple are action-only (simulate, smoke_test). The inconsistency is noticeable but not chaotic.

    Tool Count2/5

    37 tools is well above the 3-15 well-scoped range and even above the 16-25 heavy range; the generic entity_* CRUD layer plus per-entity create/update duplicates much of the surface. A more streamlined set would use either generic CRUD or specialized entity tools, not both.

    Completeness3/5

    Core resource lifecycle and testing/evaluation are covered, and entity_delete/get/list fill many gaps. However, unit test sets can be created but not executed, and tool versions are said to be 'published separately' with no corresponding tool, leaving notable dead ends.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers