Skip to main content

​
Add a hosted MCP server

Do this when the MCP server is code that AgentArea should run — a published container image, or an npm or PyPI package launched with npx or uvx. Use Connect a remote MCP server instead when somebody else already operates the server at a URL. Hosting means AgentArea provisions and supervises the workload, and the agent never reaches the server directly.

​
Prerequisites

  • An API key for the workspace.
  • The image reference, or the package name and its launch command.
  • The MCP manager reachable from the API. Managed instances cannot be provisioned without it.

​
Choose a creation path

The spec describes what the server is — image, command, and the env_schema declaring the inputs it needs. The instance is one configured copy of it.

​
Steps

​
Option A — container image, one call

The response is the instance, including its verification block. A managed instance returns 202, not 201: verification runs in the background, so the verification.status in this response is the starting state, not the outcome. Remote (url) instances verify synchronously and return 201.

​
Option B — published package

Use type: "command". The package is wrapped in the agentarea/mcp-bridge container, which listens on port 8080; you do not set a port.
Only five keys in json_spec are treated as transport: type, endpoint_url, image, command, args. Everything else — environment, headers, port — is instance configuration.

​
Option C — separate spec and instances

Create the spec once:
Then create each instance against it:

​
Trigger verification

Verification provisions the workload and polls tools/list until it answers. Run it explicitly after creating an instance:
The call returns 200 whether or not verification succeeded — the HTTP status describes the call, not the outcome. Read verification.status. A cold npx or uvx install can take minutes. Verification does not fail on a clock while the container is alive; it fails early only when the runtime reports the container dead, and is capped at 600 seconds.

​
Verify

The instance is usable when its verification succeeded and it discovered tools:
succeeded with a non-zero tool count means the server answered tools/list. There is no status column — this field is the liveness signal.

​
Troubleshooting

verification.status is failed with code: container_failed. The workload started and died. The message carries the runtime’s report — usually a missing environment variable the image requires at boot, or an image that does not exist for the node’s architecture. Fix the spec and re-verify. failed with code: list_tools_timeout. The container is alive after 600 seconds but never answered tools/list. Common causes: the image is not an MCP server, or it speaks stdio and was configured as type: "docker" rather than being launched through the bridge as type: "command". failed with code: mcp_error. The endpoint answered but the MCP handshake failed. This is a protocol-level error and is not retried. Check the server’s own logs. Stuck at in_progress. A verification interrupted by a worker restart stays in_progress until it is 12 minutes old, then the monitor marks it verification_interrupted. Re-running POST .../verify forces a fresh run without waiting. never_attempted and nothing happens. The background sweep picks up managed instances at never_attempted every 30 seconds, five at a time — unless the instance is marked lazy_provisioning, which is excluded from the sweep by design and starts on first use instead. The instance verifies but an agent cannot call it. Discovery is separate from authorization. A tool call also has to clear the task’s policy, so check Authorize a tool call.