Skip to content
AI

Operating 3forge Enterprise over MCP

This is the page an AI agent reads before driving a running 3forge Enterprise instance over MCP. It establishes which MCP surface exposes which tools, and states once the transport rules that the charting, Historical Database, and REST pages each rely on: how a read behaves, how a callback argument must be shaped, how a multi-statement write behaves, and how far a syntax check can be trusted.

The surfaces

Three distinct things are all sometimes called "MCP" in this documentation set. They are not interchangeable, and only one of them exposes the web_* / center_* / relay_* tool names used in the charting and Historical Database pages.

Surface What it is Exposes
MCP server (MCP Server) A REST plugin (MCP) built into AmiCore, served at /3forge_rest/mcp on the Web component's port by default The full console tool catalog: center_execute, web_console, web_create_chart, web_add_chart_layer, web_execute, web_debug, web_verify, web_danger, relay_addFeedhandler, and cross-component tools such as log_search and aidoc_get_documentation. This is the surface every tool name in the charting and Historical Database pages refers to.
/3forge_rest/mcp (REST API) The same endpoint, described from the REST server's side as one row in its endpoint table Nothing beyond what the MCP server row above already describes; rest_api.md documents the REST server's other endpoints (/3forge_rest/query, /version, /whoami, /stats, /admin), which are a separate, synchronous transport, not MCP tools
MCP plugin for coding tools (3forge MCP Plugin) A client-side plugin (3forge-mcp) installed into Claude Code, Codex, or Copilot Nothing of its own. It bundles skills, agents, and commands, and connects to the MCP server above as its 3forge-runtime MCP connection. It is a packaged client, not a fourth surface.

So there are really two runtime surfaces: the MCP server (tool calls, asynchronous, the one charting and Historical Database pages use) and the REST query endpoint (/3forge_rest/query, synchronous, row-returning). The MCP plugin is a way of reaching the first from a coding tool, not a separate surface.

Shared transport rules

These rules hold for every tool call against the MCP server (/3forge_rest/mcp). Each feature page states the one sentence relevant to it and links here for the rest.

A read returns a deferred handle, not rows

Applies to: the MCP server. A SELECT, an aggregate, a join, or count(*) sent as Center SQL over an MCP tool call (for example center_execute) does not return row values. It returns a deferred-query handle:

1
Deferred-query handle -- the query is async and its result is not materialized in agent tools.

Metadata queries are the exception and do return materialized rows synchronously: SHOW TABLES, DESCRIBE TABLE, and DIAGNOSE TABLE all work as verification steps over MCP for exactly this reason.

To read actual row values, an agent needs a synchronous transport: the REST query endpoint (GET /3forge_rest/query, see REST API) or JDBC. For a chart, the practical consequence is that data is never read back with a SELECT over MCP; it is materialized into a datamodel output table first and inspected with web_console(op="datamodelTables") — see Building Charts over MCP.

The REST query endpoint is disabled by default

The shipped ami.rest.plugin.classes is *,!QUERY,!ADMIN, which excludes /3forge_rest/query while leaving the MCP plugin enabled (MCP is matched by * and not excluded). Out of the box, MCP tools can create, load, and verify data by row count, but nothing on the MCP server returns rows. A deployment that wants row data over REST must add QUERY to ami.rest.plugin.classes. See Configuration.

A callback argument must be a single string

Applies to: the MCP server, wherever a tool takes an amiscript callback body (for example importing a datamodel with web_execute(op="importDatamodel"), or a chart's onProcess). The value must be one string with embedded \n, not an array of lines. An array is comma-joined by the transport and fails validation:

1
Callback 'onProcess': Error ... Unexpected char: ,

See Building Charts over MCP for the sequence a chart follows.

Send one write statement per call

Applies to: the MCP server, for Center SQL writes (INSERT, UPDATE, DELETE) issued through a tool such as center_execute. A multi-statement write batch does not reliably apply every statement: three INSERT statements sent in one call committed only one row in testing, while the same three sent as separate calls committed all three. The miss is silent, because the call returns a deferred handle rather than a per-statement row count.

A single INSERT with multiple value tuples is one statement and is unaffected:

1
INSERT INTO Trades VALUES (20260101,'IBM',100,183.4),(20260101,'AAPL',250,201.1);

Confirm every write with a row-count check rather than trusting the call to report failure. See Historical Database: Operating over MCP.

The syntax pre-check is not a reliable gate

Applies to: the MCP server, specifically center_verify(op="amisql"). It is described as a syntax pre-check, but it returns OK for input the Center then rejects at execution: SELECT FROM WHERE passes the check and fails with Error At Line 1, position 7. An agent that treats a passing check as permission to proceed will submit statements that fail. Verify a statement by executing it and handling the execution error, not by trusting the pre-check alone.

The session-id parameter name differs across tools

Applies to: the MCP server. Some tools take __SESSIONID (web_console, web_script, web_create_chart); others require __SESSIONID_or_HEADLESSNAME (web_execute(op="executeDatamodel"), web_console(op="datamodelTables")). Pass both to be safe. See Building Charts over MCP.

Rows read over the REST query endpoint are a separate contract

Applies to: /3forge_rest/query, not the MCP server. Where an agent falls back to the REST query endpoint to get materialized rows, that endpoint has its own contract: display=jsonMaps returns tables as an object keyed by table name with alphabetized row keys, while json/jsonRows return tables as an array preserving SELECT order; errors come back in two shapes (a 200 with status:"error" for a statement error the Center reached, or a 400 with a non-JSON body for a request rejected before running); and a result is capped at limit (default 10000) with no indication that rows were withheld. None of this applies to MCP tool calls, which never return rows in the first place. See REST API for the full contract.

Feature guides