Agents (MCP)

i2b answers the Model Context Protocol, so an agent can read what an analysis found and suggest corrections to it. It speaks JSON-RPC 2.0 over POST /api/mcp, with a token issued from your account in the Authorization header.

Two rights, and the default is read

A token reads. A token may also suggest, if the person who issued it asked for that when they issued it. There is no third right, and nothing an agent does applies to a migration until a person accepts it.

Whatever an agent writes, it writes a suggestion. The level a decision is recorded at is set by the server and never by the caller: a tool call that announces itself as a person’s decision is stored as the agent’s proposal, like every other.

What a token may read

• get_rightsWhat this token may do, and what each right permits. Every token may read; only a token its owner gave the propose right may suggest anything. Ask this first: it is how a client refuses a step it cannot run instead of discovering that by writing.
• list_workspacesThe workspaces this i2b account has opened to agents. Each one is a database somebody analysed; the id is what the other tools take. Workspaces that have not been opened are not listed at all.
• get_correctionsWhat a person decided by hand about the relationships in one workspace: which links they asserted, which they rejected, and which fields they remapped. ASSERTED means a human looked and decided - it outranks a declared foreign key, and nothing but a person may write it.
• get_schema_mapThe shape of the database in one workspace, if its owner chose to keep it: tables, columns and types, which columns are keys, and every relationship with how it was established - EXTRACTED from a constraint, DECLARED by the engine adapter, DATA_INFERRED from values lining up, or INFERRED from a name. No values from the database are ever stored or returned. Answers null where nothing is kept, which is the default.
• get_pipelineThe process the owner of this workspace assembled: which steps, in which order, and what each one does. Steps are data - the same ones their workbench shows. Running them is theirs; this is how you compose with what they are actually doing rather than with what i2b can do in general.
• list_quotesWhat the analyses on this account measured: the difficulty level (1-4), the size band, how many tables, the price band, and what would not be carried across. i2b does not keep the schema itself - this measurement is what survives an analysis.

What a token may suggest

These need the propose right. Without it the call is refused and says so, which is how a client finds out before it writes rather than afterwards — that is what get_rights is for.

• propose_relationshipSuggest that one column points at another table. It is recorded as PROPOSED and changes nothing: the analysis, the dry run and the migration carry on as if it were not there, and it is shown to the account holder to accept or reject. Only a person may assert a relationship. Give a reason - it is what they will read when deciding.
• propose_mappingSuggest which column of a table carries a canonical field - for one entity of that table, since a table can hold several. Recorded as PROPOSED and applied to nothing until the account holder accepts it. Use get_schema_map to see the columns and get_corrections to see what has already been decided.
• propose_nested_keySuggest what a value nested inside a table is. Three shapes: a key inside one cell (a serialised array or a JSON object), an attribute code in a store like Magento's EAV, or a whole table per field, which is what Drupal does. Say which field it carries, or that it carries none. Recorded as PROPOSED and applied to nothing until the account holder accepts it.

Limits on writing

100 unanswered proposals per workspace, 200 a day per token, and a reason of at most 500 characters. A reason is a sentence, not a place to put a payload.