MCP 2.0 migration guide

Monghoul 2.0 ships version 2 of the MCP tool catalog. This page is for authors of MCP clients and for people who keep prompts or scripts that name 1.x tools. The page lists the new name of each tool and the arguments that changed.

What changed

• Every tool has a new name, except discover_tools, enable_tools and disable_tools. The 77 tools of 2.0 carry every 1.x tool. The table below maps each 1.x name to the 2.0 tool that carries it.
• A 1.x name runs nothing. 2.0 has no alias and no implicit translation. A call to execute_query answers an error that names query_execute and this guide, and AI Activity shows the same text, so the user sees why the assistant stopped.
• The server names its own map. server_info answers renamedTools, the same 1.x-to-2.0 map, so a client can read it from the server.
• Arguments are strict. An argument the schema does not name is refused at input. In 1.x it was ignored.
• Two tools are new. server_info answers the API version, the runtime generation, the operation ID format, the providers and the name map. resource_describe describes a connection, a database or a collection, with what its provider can do.
• A saved tool switch moves with its tool. On the first launch of 2.0, AI Access moves each saved switch to the 2.0 tools that carry its 1.x tool. A merged tool whose 1.x tools had different switches stays off and is marked for review, so a merge never turns on a tool the user turned off.

Setup does not change

The address, the token and the client snippets are the same as in 1.x. A client that connected to 1.x connects to 2.0 with no change, and lists the 2.0 tools. Only the tool names and arguments the client sends change.

Running a query

execute_query becomes query_execute, and the call names its operation.

1.x execute_query	2.0 query_execute
connectionId	connectionId
dbName	request.database
code	request.text
(none)	request.version: 1, request.providerId: "mongodb", request.kind: "javascript"
resultLimit	limits.resultLimit
title	presentation.title
(none)	presentation.mode: "tab" or "headless"
(none)	operationId, required
(none)	waitMs, how long the call waits for a result before it answers accepted

The operation ID is the runtimeGeneration from server_info, a dot, then 1 to 64 of A-Z a-z 0-9 _ -. Choose a new ID for each new query. Send the same ID again only to retry the same call: an ID never runs twice, and a retry answers the first call’s state.

{
  "operationId": "1Hq4faReE8.orders-by-status",
  "connectionId": "N0yioPOMIcNG2o8eDoREA",
  "request": {
    "version": 1,
    "providerId": "mongodb",
    "kind": "javascript",
    "database": "shop",
    "text": "db.collection('orders').aggregate([{ $group: { _id: '$status', n: { $sum: 1 } } }])"
  },
  "limits": { "resultLimit": 100 }
}

The answer has a state:

• completed: the run ended, with its outcome and the result bounded to 1 MiB.
• accepted: the run continues after waitMs. Poll operation_get, then read result_get.
• review-required: the user’s approval policy holds the query for review. Poll operation_get.
• rejected: refused before it ran, with error.code.

Reading a result

get_tab_result read a tab’s latest result. In 2.0 a result belongs to an operation.

• result_get {operationId} reads that operation’s own result, never a later run of its tab. The envelope is {apiVersion, operationId, providerId, payloadAvailability, result, projection}. payloadAvailability is live, stored, suppressed (the connection keeps documents off disk and the app no longer holds them) or expired. projection.complete is false when whole documents were left out to fit 1 MiB.
• operation_get {operationId} reads the state of a request: awaiting-review, running, completed, rejected, expired or unknown. With no operationId it lists the requests that wait for the user or were decided recently. It replaces check_approval.
• To read a run the user started, take latestOperationId from tab_get or workspace_get.

Editing a tab

update_tab_code {tabId, code} becomes workspace_update {tabId, code, expectedRevision}. Send the tab’s codeRevision from tab_get or workspace_get as expectedRevision. A stale revision answers REQUEST_CONFLICT with the current code, so the client reads it again and does not write over the user’s edit. tab_close refuses a tab with a running query or a pending review.

Connections

• add_connection {name, uri, color, timeout} becomes profile_create {profile}. profile is the input the connection editor saves: every field is present, with null for one that is not set, and each secret is {action: "set", value, persist} or {action: "keep"}. The answer is {id, name, color}, and no answer carries a secret.
• delete_connection becomes profile_delete {connectionId, favorites}. favorites is "keep" (the default: the saved queries stay with no connection) or {moveTo: connectionId}.
• sync_databases and sync_collections become one tool, resource_list {connectionId, dbName}. Without dbName it lists the databases; with it, the collections of that database.

Merged tools

1.x tools	2.0 tool	The argument that tells them apart
pin_collection, unpin_collection	pin_set	pinned: true or false
navigate_to_connection, navigate_to_database, navigate_to_collection	sidebar_reveal	dbName and collectionName, each optional
expand_in_sidebar, collapse_in_sidebar	sidebar_set_expanded	expanded: true or false
split_panel, split_and_move_tab	panel_split	tabId, optional: with it the tab moves into the new panel
list_running_tasks, get_task_progress	operation_list	operationId, optional
get_tab_result, check_approval	result_get, operation_get	see “Reading a result”

Errors

A failed call answers isError: true. A refusal with a code is JSON with status: "error" and the code, such as PROFILE_NOT_FOUND, REQUEST_CONFLICT, TAB_UNAVAILABLE or OPERATION_RUNNING; query_execute answers its refusals as state: "rejected" with error.code. A connection of a database type this build cannot use answers PROVIDER_UNAVAILABLE, and one of a type with no MongoDB tools answers CAPABILITY_UNAVAILABLE, before anything runs. A connection or a database outside the scope the user set answers the text “Out of MCP scope”, which is a settings decision and not a transient error. Other failures answer a sentence that says what went wrong.

Every 1.x name

The 82 tools of 1.x and the 2.0 tools that carry them. Three keep their names: discover_tools, enable_tools and disable_tools. server_info answers the same map in renamedTools.

1.x tool	2.0 tool
activate_tab	tab_activate
add_connection	profile_create
analyze_schema	mongodb_schema_analyze
calculate_collection_stats	mongodb_collection_stats
calculate_db_size	mongodb_database_stats
cancel_task	operation_cancel
check_approval	operation_get
clear_operation_logs	activity_clear
clone_collection	mongodb_collection_copy
clone_database	mongodb_database_copy
clone_tab	tab_clone
collapse_in_sidebar	sidebar_set_expanded
create_markdown_tab	tab_open_markdown
create_query_tab	workspace_open
create_sidebar_folder	sidebar_folder_create
create_theme	theme_create
delete_connection	profile_delete
delete_theme	theme_delete
detach_tab	window_detach
disable_tools	disable_tools
discover_tools	discover_tools
enable_tools	enable_tools
execute_query	query_execute
expand_in_sidebar	sidebar_set_expanded
find_join_path	mongodb_map_join_path
get_active_theme	theme_get
get_database_findings	mongodb_map_findings
get_database_map	mongodb_map_get
get_detached_windows	window_list
get_log_response_storage_config	activity_capture_get
get_replica_set_status	mongodb_replica_status
get_tab	tab_get
get_tab_result	operation_get, result_get
get_task_progress	operation_list
get_theme_schema	theme_schema_get
get_workspace	workspace_get
list_connections	profile_list
list_favorite_queries	favorite_list
list_operation_logs	activity_list
list_pinned_collections	pin_list
list_running_tasks	operation_list
list_sidebar_tree	sidebar_tree_get
list_themes	theme_list
move_sidebar_node	sidebar_node_move
move_tab_to_panel	panel_move_tab
navigate_to_collection	sidebar_reveal
navigate_to_connection	sidebar_reveal
navigate_to_database	sidebar_reveal
open_database_map	mongodb_map_open
pin_collection	pin_set
reattach_tab	window_reattach
remove_favorite_query	favorite_remove
remove_panel	panel_remove
remove_sidebar_node	sidebar_node_remove
remove_tab	tab_close
rename_sidebar_folder	sidebar_folder_rename
reorder_sidebar_nodes	sidebar_node_reorder
reorder_tabs	tab_reorder
resize_panels	panel_resize
restore_tab	tab_restore
save_chart_config	chart_set
save_favorite_query	favorite_save
scan_database_map	mongodb_map_scan
search_tabs	tab_search
set_active_theme	theme_activate
set_editor_split_size	tab_set_split
set_log_response_storage_config	activity_capture_set
set_relationship_verdict	mongodb_map_set_verdict
set_result_fullscreen	tab_set_fullscreen
show_toast	toast_show
split_and_move_tab	panel_split
split_panel	panel_split
sync_collections	resource_list
sync_databases	resource_list
sync_indexes	mongodb_index_list
test_connection	profile_test
toggle_sidebar	sidebar_set_visible
toggle_sidebar_folder_collapsed	sidebar_folder_set_collapsed
unpin_collection	pin_set
update_tab_code	workspace_update
update_theme	theme_update
update_window_bounds	window_set_bounds