Deploy and connect through MCP

Deploy a Recurse agent as an MCP tool when another agent needs to invoke it repeatedly with new inputs. A deployment pins one tested Recurse agent revision and exposes its manifest interface as a tool. Each tool call starts a new serverless run against that revision.

Your coding agent prepares and tests the deployment. You approve the measured revision, public tool contract, resource ceilings, and secret bindings before it proceeds. The workflow is:

1. Evaluate a revision with direct runs.
2. Approve its interface, evidence, resources, and secret bindings.
3. Create the deployment.
4. Connect the MCP host.
5. Verify one representative tool call.

Approve the revision and interface

Direct runs are for developing the prompt, tools, and verifiers. Before deployment, ask your coding agent to show that representative runs:

• Meet the required constraints and quality target.
• Return the expected structured result and artifacts.
• Fit the intended time and cost allowance.
• Record known failures and limitations.

The manifest becomes the MCP tool's interface. metadata.name supplies its name, metadata.summary tells a calling agent when to use it, inputs defines what callers supply, and outputs defines the structured result. Review those fields from the perspective of a calling agent that has no other project context.

Let the coding agent create the deployment

After approval, the coding agent runs:

recurse deploy ./my-agent --as mcp

Recurse builds and prepares the package, then creates the deployment. The CLI prints the deployment ID, endpoint, and resource settings. Ask the coding agent to record the deployment ID with the exact Recurse agent revision, model, resources, and secret bindings.

The default ceilings are 1 CPU and 1,024 MiB per call. A deployment can use different defaults when its tools require them:

recurse deploy ./my-agent --as mcp --cpu 2 --memory-mib 2048

Required secret bindings use --secret ENV=NAME. Inputs are supplied by each caller; deploy does not accept --inputs.

Connect all published apps

One connection exposes every published Recurse app:

recurse mcp serve

Configure the host with command recurse and arguments ['mcp', 'serve']. For hosts that connect directly over HTTP, use https://api.recurse.run/mcp/all and approve the Recurse sign-in prompt. Consent includes apps published later; runs use the connected account's wallet.

Published tools are named apps.<listing_slug> and keep each app's input schema. Private deployments require their own connection.

Connect the host to one deployment

The MCP host launches a local bridge for the deployment:

recurse mcp serve DEPLOYMENT_ID

Use the host's documented MCP configuration format with these values:

The bridge needs access to the operating-system keychain containing the login created by recurse login. Do not put device credentials in the host configuration. A deployment ID identifies the reusable tool; a run ID identifies one invocation and cannot replace it.

Configure the host's startup timeout to allow the local bridge to start, and its tool-call timeout to cover the run. Runs can continue while funded, up to the provider's fixed 24-hour limit with three minutes reserved for finalization. A host timeout cannot extend that limit. For Codex, set startup_timeout_sec = 180 and tool_timeout_sec = 87000; other hosts need comparable headroom. Host cancellation requests cancellation of the active call.

Verify the connected tool

After the host reloads its configuration, ask your coding agent to:

1. Confirm that the host discovers the tool and expected input schema.
2. Invoke it with a representative input used during evaluation.
3. Compare the structured result and artifacts with the direct-run evidence.
4. Report the new run ID and the resource ceilings requested for the call.

A real tool invocation starts billable execution. Completed results can include recurse://artifact/... links for hosts that support MCP resources.

Replace a deployed revision

Local edits do not change an existing deployment. After changing the prompt, tools, dependencies, input/output contract, or model, your coding agent must:

1. Evaluate the revision with direct runs.
2. Create a new deployment with the intended resources and secret bindings.
3. Replace the deployment ID in the host configuration.
4. Reload the connection and verify discovery and one representative call.

Existing deployments continue to serve their pinned revision and retain the model resolved when they were prepared. Changing the model or any packaged file requires a new revision and deployment.