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

Connect your AI Agents to Namespace in minutes

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

Start building for free

Read docs

Namespace

Learn more about Merge Agent Handler

Available tools

create_ingress

Expose a port on a running instance through a public HTTPS hostname. Requests need a Namespace token unless an httpmatchrule allows them. Namespace has no API to delete an ingress; it ends with the instance. Use list_instances for instance IDs.

list_ingresses

List the public ingresses (names and hostnames) on an instance. Use list_instances to find instance IDs.

get_kubernetes_config

Get a kubeconfig for an instance created with Kubernetes enabled (createinstance featureconfiguration). Client credentials are REDACTED unless revealsecret is true; set it only when the user needs a working kubeconfig. Use listinstances to find instance IDs.

get_ssh_config

Get an SSH endpoint, username and host keys for an instance or one of its containers. The private key is REDACTED unless revealsecret is true; set it only when the user needs to connect. Use listinstances for instance IDs and get_instance for container names.

get_vnc_config

Get the VNC endpoint and username for a macOS instance's desktop; Linux instances return an error. The password is REDACTED unless revealsecret is true; set it only when the user needs to connect. Use listinstances to find instance IDs.

get_network_configuration

List the source IP ranges (CIDRs) that this workspace's instances use for outbound traffic, e.g. to allowlist them in a firewall.

run_command

Run a command on an instance (or one of its containers) and wait for it; returns exit code, stdout and stderr (last 64 KB each). Times out after 45 seconds, leaving it running; do not retry blindly. Run longer jobs in the background (nohup ... &). Commands can change the instance. Use listinstances for instance IDs and getinstance for container names.

list_instances

List compute instances in the configured region. By default only PENDING, CREATING and RUNNING instances; set includecompleteruns for finished ones. Filter by creation time or labels. The API returns no cursor, so if pageinfo.hasnextpage is true, raise limit (max 100) or narrow with notolderthan or labelfilter.

get_instance

Get one instance's status, shape, deadline, containers, exported URLs and access endpoints. Credentials are omitted; use getsshconfig or getkubernetesconfig for those. Use list_instances to find instance IDs.

create_instance

Create a billable compute instance with a shape, optional containers, volumes and ingresses. Call getconcurrency first to check capacity, then waitinstance until it is RUNNING. Set a deadline and call destroy_instance when done.

destroy_instance

Permanently destroy an instance and its ephemeral state. Cannot be undone. Use list_instances to find instance IDs.

wait_instance

Block until an instance (or one of its containers) is ready, then return its current metadata. Times out after 45 seconds; call again or poll getinstance to keep waiting. Use after createinstance or startcontainers. Container names and IDs come from getinstance.

extend_instance

Change when an instance is destroyed: set exactly one of extendby (add time), ensureminimum (minimum remaining lifetime) or newdeadline (absolute). Workspace policy may cap it. Use listinstances to find instance IDs.

start_containers

Start more containers on a running Linux instance. Namespace has no API to stop a single container; destroyinstance ends them all. Use listinstances to find instance IDs and wait_instance to wait for a container.

list_instance_notifications

List the latest lifecycle event (status change) per instance, newest first. Optionally filter by instance IDs from listinstances, or only events not yet delivered to the HTTP callback. There is no cursor: if pageinfo.hasnextpage is true, raise limit (max 100) or filter by instance_ids.

get_instance_logs

Get log lines for one or more instances (running or finished), optionally filtered by container and time range. Paginate with pageinfo.cursor. Use listinstances with includecompleteruns to find IDs of finished instances.

get_instance_diagnostics

Get diagnostics for an instance, currently its out-of-memory (OOM) kill events. Use when an instance or container died unexpectedly. Use list_instances to find instance IDs.

list_instance_egress

List outbound connections (domains, resolved IPs, allow/deny decision) an instance made, optionally within a time range. Paginate with pageinfo.cursor. Use listinstances to find instance IDs.

get_instance_metrics

Get CPU, memory, I/O-wait and storage time series for an instance, optionally within a time range. Use list_instances to find instance IDs.

list_cache_volumes

List the workspace's cache volume generations with tag, size, state and which instance each is attached to. The API returns all of them in one response. Use listvolumetag_summaries for a per-tag view.

get_cache_volume

Get one cache volume generation by ID, including attachment history and cached container images. Use listcachevolumes to find IDs.

list_volume_tag_summaries

List one summary per cache volume tag: size and each generation with its state and attachment. The API returns all tags in one response. Use the tag with getvolumetag_summary.

get_volume_tag_summary

Get the summary for one cache volume tag: size and each generation with its state and attachment. Use listvolumetag_summaries to find tags.

list_persistent_volumes

List persistent (durable) volumes, optionally filtered by tag or site. Paginate with pageinfo.cursor. Persistent volumes are created by createinstance volumes with persistency_kind 'PERSISTENT'.

get_persistent_volume

Get one persistent volume by ID and tag, including a destroyed one, which listpersistentvolumes no longer returns. Both must match the same volume or Namespace returns not found. Use listpersistentvolumes to find them.

destroy_persistent_volumes

Permanently destroy persistent volumes matching either IDs or tags (not both), with their data. Cannot be undone. Use listpersistentvolumes to find IDs and tags first. A volume stays in use for about 30 seconds after its instance is destroyed; retry if Namespace reports it still in use.

list_persistent_volume_snapshots

List the snapshots of one persistent volume, identified by ID or tag. Use listpersistentvolumes to find them. A snapshot ID can seed a new volume via createinstance volumes.fromsnapshot_id.

destroy_persistent_volume_snapshot

Destroy a persistent volume snapshot: Namespace marks it abandoned (abandonedAt) and stops using it as a base for new volumes. Existing volumes are not affected. Use listpersistentvolume_snapshots to find snapshot IDs.

get_usage

Get compute and build usage (unit and wall minutes) for a date range within one month, in total and per day. Defaults to the current month. Filter by platform, shape, GitHub repository or runner profile.

get_volume_usage

Get cache and persistent volume storage usage for a date range within one month. Defaults to the current month.

get_artifact_usage

Get object storage usage (storage GB-minutes and bytes read) per product, such as the container registry or build caches, for a date range within one month. Defaults to the current month.

get_usage_time_series

Get usage over an arbitrary time range as a time series, optionally filtered (platform, shape, GitHub repo/branch) and broken down by a dimension. Use get_usage for simple monthly totals.

generate_report

Generate a per-instance report (resources, peak CPU/RAM use, timing) for instances created in a time range, optionally filtered. Returns at most limit entries and stops after 45 seconds; if truncated is true, truncation_reason says which, and narrowing the range or filtering helps both.

get_concurrency

Get current usage and limits (instances, vCPUs, memory) for each concurrency pool. Check before create_instance to see whether capacity is available.

validate_credential

Check that the Namespace tenant token and compute region work by listing one instance.

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}