codex-as-mcp

Overview Schema Source Related Servers Discussions Admin

spawn_agent

Spawn an autonomous Codex subagent to work on tasks in your current directory. Provide a prompt with full instructions and get back the agent's final response.

Instructions

Spawn a Codex agent to work inside the current working directory.

The server resolves the working directory via ``os.getcwd()`` so it inherits
whatever environment the MCP process currently has.

Args:
    prompt: All instructions/context the agent needs for the task.

Returns:
    The agent's final response (clean output from Codex CLI).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "prompt": "<prompt>"
    },
    "name": "spawn_agent"
  }
}

Input Schema

Name	Required	Description	Default
`prompt`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Aug 6, 2026

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral disclosure burden. It does disclose that the working directory inherits from the MCP process and that the return is clean Codex CLI output, which is useful. However, it does not mention potential side effects, permissions, or execution constraints, leaving notable gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately structured with a clear opening line, a brief explanatory paragraph, and then Args/Returns sections. It is mostly concise, though the cwd resolution explanation is slightly verbose. Overall, it earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and an output schema, the description covers the essential operational detail (cwd resolution) and the return format. It is complete enough for an agent to invoke the tool correctly, though it could add a note about the parallel sibling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides zero parameter descriptions, but the description's 'Args' section explains that 'prompt' should contain all instructions/context needed for the task. This adds meaningful semantics beyond the raw schema, compensating for the lack of schema-description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool spawns a Codex agent in the current working directory, providing a specific verb and resource. However, it does not explicitly distinguish from the sibling tool spawn_agents_parallel, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains how the working directory is resolved but gives no explicit guidance on when to use this tool versus the parallel alternative. There is no mention of criteria like single vs. multiple agents, so the agent is left without clear selection cues.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server