Merge Unified's Terraform integration Merge Agent Handler's Terraform MCP server

Connect your AI Agents to Terraform in minutes

Merge lets you securely connect your agents to Terraform and thousands of tools instantly

Start building for free

Read docs

Terraform

Learn more about Merge Agent Handler

Available tools

list_configuration_versions

List a workspace's configuration versions (uploaded Terraform config snapshots), newest first, with pagination. Use listworkspaces to find workspace IDs and getconfiguration_version for one version's details.

get_configuration_version

Get one configuration version by ID. Use listconfigurationversions to find configuration version IDs.

get_account_details

Get the user or service account the API token authenticates as. Use this to confirm which identity the connection runs as before reading or writing data.

list_organizations

List the HCP Terraform organizations the API token can access, with pagination. Use get_organization for one organization's full record. Organization names are the input to most other tools.

get_organization

Get one organization by name. Use list_organizations to find organization names.

get_organization_entitlements

Get the feature entitlement set for an organization — which features (teams, cost estimation, policy enforcement, etc.) its plan includes. Use list_organizations to find organization names.

list_projects

List projects in an organization, with pagination and an optional name search. Use getproject for one project's record. Use listorganizations to find organization names.

get_project

Get one project by ID. Use list_projects to find project IDs.

create_project

Create a project in an organization. Projects group workspaces. Use list_organizations to find organization names. Returns the new project's ID.

update_project

Update a project's name or description. Use list_projects to find project IDs.

delete_project

Delete a project. The project must contain no workspaces or stacks or the call is rejected. Use list_projects to find project IDs.

move_workspaces_to_project

Move one or more workspaces into a project. Use listprojects to find project IDs and listworkspaces to find workspace IDs.

list_workspace_runs

List runs in a workspace, newest first, with pagination. Filter with status or operation. Use getrun for one run's full record and listworkspaces to find workspace IDs.

list_organization_runs

List runs across an entire organization, newest first, with pagination. Filter with status. Use listworkspaceruns to scope to one workspace and list_organizations to find organization names.

get_run

Get one run by ID, including its status and links to its plan and apply (in relationships). Use listworkspaceruns to find run IDs.

create_run

Create (queue) a run on a workspace from its latest configuration or a given configurationversionid; set isdestroy for a teardown or planonly for a speculative plan. Use listworkspaces to find workspace IDs. Poll getrun for status, then applyrun to apply. Can apply changes immediately when autoapply is set or the workspace auto-applies.

apply_run

Apply a run that has finished planning and is awaiting confirmation. This executes the planned changes against real infrastructure. Use getrun to confirm the run's status is 'planned' first, and listworkspace_runs to find run IDs.

discard_run

Discard a run awaiting confirmation, abandoning its plan without applying. Use listworkspaceruns to find run IDs.

cancel_run

Cancel a run that is currently planning or applying, interrupting it. For a run that will not cancel normally, an admin can force-cancel it (not exposed here). Use listworkspaceruns to find run IDs.

list_run_comments

List the comments on a run, with pagination. Use listworkspaceruns to find run IDs.

create_run_comment

Add a comment to a run. Use listworkspaceruns to find run IDs.

get_plan

Get one plan's metadata — status and the counts of resources to add, change, and destroy. Find the plan ID in a run's relationships.plan from getrun. For the full structured changes, use getplanjsonoutput.

get_plan_json_output

Get planned resource actions from a plan's structured JSON output without attribute values; sensitive values are never returned. Find the plan ID in a run's relationships.plan from getrun. Use getplan for counts.

get_apply

Get one apply's metadata — status and the counts of resources added, changed, and destroyed. Find the apply ID in a run's relationships.apply from get_run.

list_run_triggers

List a workspace's run triggers, with pagination. Pass triggertype='inbound' for triggers that start runs in this workspace, or 'outbound' for ones it sets off elsewhere. Use listworkspaces to find workspace IDs.

get_run_trigger

Get one run trigger by ID. Use listruntriggers to find run trigger IDs.

create_run_trigger

Create a run trigger so a successful apply in the source workspace queues a run in the target workspace. Use listworkspaces to find both workspace IDs. Returns the new run trigger's ID; delete it with deleterun_trigger.

delete_run_trigger

Delete a run trigger. Use listruntriggers to find run trigger IDs.

list_state_versions

List a workspace's state versions, newest first, with pagination. Identify the workspace by organizationname and workspacename (not ID). Use listworkspaces to find workspace names, and getstate_version for one version's details.

get_state_version

Get one state version by ID. Use liststateversions to find state version IDs.

get_current_state_version

Get a workspace's current (latest) state version. Use list_workspaces to find workspace IDs.

list_state_version_outputs

List the named outputs of a state version, with pagination. Sensitive output values are always redacted to null by the connector. Use liststateversions to find state version IDs.

get_state_version_output

Get one state version output by ID; sensitive output values are always redacted to null by the connector. Use liststateversion_outputs to find output IDs.

get_current_state_version_outputs

Get the outputs of a workspace's current state version — the quickest way to read a workspace's output values. Sensitive output values are always redacted to null by the connector. Use list_workspaces to find workspace IDs.

list_team_access

List the teams that have access to a workspace and their access levels, with pagination. Use listworkspaces to find workspace IDs and addteam_access to grant a new team access.

get_team_access

Get one team access grant by ID. Use listteamaccess to find team access IDs.

add_team_access

Grant a team access to a workspace. Set access to 'read', 'plan', 'write', or 'admin' for a fixed level, or 'custom' and set runs/variables/stateversions individually. Use listteams to find team IDs and list_workspaces to find workspace IDs. Returns the new grant's ID.

update_team_access

Update a team's access level on a workspace. Use listteamaccess to find team access IDs.

remove_team_access

Remove a team's access to a workspace. Use listteamaccess to find team access IDs.

list_teams

List teams in an organization, with pagination and an optional name search. Use getteam for one team's record and listorganizations to find organization names.

get_team

Get one team by ID. Use list_teams to find team IDs.

create_team

Create a team in an organization. Set visibility and organizationaccess to control what the team can see and manage. Use listorganizations to find organization names. Returns the new team's ID.

update_team

Update a team's name, visibility, or organization access. Use list_teams to find team IDs.

delete_team

Delete a team. Use list_teams to find team IDs.

list_organization_memberships

List the members of an organization with their user IDs, usernames, and emails. Use this to find the username for addteammembers and removeteammembers. Filter with query, email, or status. Use list_organizations to find organization names.

add_team_members

Add members to a team by HCP Terraform username (NOT user ID 'user-...'). Use listorganizationmemberships to find usernames and list_teams to find team IDs. The users must already be members of the organization.

remove_team_members

Remove members from a team by HCP Terraform username (NOT user ID 'user-...'). Use listorganizationmemberships to find usernames and list_teams to find team IDs.

validate_credential

Check that the HCP Terraform API token works by reading the authenticated account.

list_variable_sets

List an organization's variable sets, with pagination. Variable sets hold reusable variables applied across workspaces. Use getvariableset for a set's metadata, listvariablesinvariableset for its variable keys, and list_organizations to find organization names.

get_variable_set

Get one variable set by ID. Its relationships.vars contains only variable IDs; use listvariablesinvariableset for keys and metadata. Use listvariablesets to find variable set IDs.

list_variables_in_variable_set

List the Terraform and environment variables in a variable set. Sensitive values are always redacted to null by the connector. Use listvariablesets to find variable set IDs.

create_variable_set

Create a variable set in an organization. Set isglobal=true to apply it to all workspaces, or apply it selectively with applyvariablesettoworkspaces. Use listorganizations to find organization names. Returns the new set's ID.

update_variable_set

Update a variable set's name, description, global flag, or priority. Use listvariablesets to find variable set IDs.

delete_variable_set

Delete a variable set. Use listvariablesets to find variable set IDs.

create_variable_in_variable_set

Add a variable to a variable set. key and category are required. Use listvariablesets to find variable set IDs. Returns the new variable's ID.

delete_variable_in_variable_set

Remove a variable from a variable set. Use listvariablesinvariableset to find variable IDs.

apply_variable_set_to_workspaces

Apply a variable set to one or more workspaces, so its variables take effect there. Use listvariablesets to find variable set IDs and list_workspaces to find workspace IDs.

remove_variable_set_from_workspaces

Remove a variable set from one or more workspaces. Use listvariablesets to find variable set IDs and list_workspaces to find workspace IDs.

list_workspace_variables

List all Terraform and environment variables set on a workspace. Use list_workspaces to find workspace IDs. Sensitive values are returned as null.

create_workspace_variable

Create a Terraform or environment variable on a workspace. key and category are required; set sensitive=true to hide the value. Use list_workspaces to find workspace IDs. Returns the new variable's ID.

update_workspace_variable

Update a workspace variable's value, key, description, category, or flags. Use listworkspacevariables to find variable IDs. Once a variable is sensitive it cannot be made non-sensitive.

delete_workspace_variable

Delete a variable from a workspace. Use listworkspacevariables to find variable IDs.

list_workspaces

List workspaces in an organization, newest change first. Filter with searchname, searchtags, projectid, or currentrunstatus; order with sort. Returns pageinfo.nextpage for the next page. Use getworkspace for one workspace's full record and list_organizations to find organization names.

get_workspace

Get one workspace by ID. Use list_workspaces to find workspace IDs.

create_workspace

Create a workspace in an organization. Only name is required. Optionally set executionmode, terraformversion, workingdirectory, autoapply, and projectid. Use listorganizations to find organization names and list_projects to find project IDs. Returns the new workspace's ID.

update_workspace

Update a workspace's settings (name, description, executionmode, terraformversion, workingdirectory, autoapply). Use list_workspaces to find workspace IDs.

delete_workspace

Delete a workspace and everything in it, without checking whether it still manages resources — this can orphan live infrastructure. Prefer safedeleteworkspace, which refuses if the workspace still manages resources. Use list_workspaces to find workspace IDs.

safe_delete_workspace

Delete a workspace only if it manages no resources; HCP Terraform refuses the call otherwise, so this cannot orphan live infrastructure. This is the preferred delete. Use list_workspaces to find workspace IDs.

lock_workspace

Lock a workspace so no new runs can start. Use unlockworkspace to reverse it. Use listworkspaces to find workspace IDs.

unlock_workspace

Unlock a workspace you hold the lock on, re-enabling runs. For a lock held by another user or a stuck run, use forceunlockworkspace. Use list_workspaces to find workspace IDs.

force_unlock_workspace

Force-unlock a workspace locked by another user or a stuck run. Requires admin access to the workspace. Prefer unlockworkspace for a lock you hold. Use listworkspaces to find workspace IDs.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}