Skip to content
TilloTech Docs

MCP, tools, and subagents

Skills describe how to work. Tools provide capability. MCP connects Codex or Claude Code to external tools and context. Subagents provide separate model contexts for independent work. Keep those responsibilities and their security boundaries distinct.

When to use MCP

Use MCP when current data or an action lives outside the local repository, such as an issue tracker, design tool, source host, browser, observability system, or internal knowledge service. An MCP server may expose tools, readable resources, and reusable prompts.

Do not build MCP merely to wrap a stable local command. A composable CLI is simpler to test, use in CI, and invoke from a skill. Do not use web search for authorized private workspace data when an approved connector or MCP server is available.

Configure Codex MCP

Codex stores MCP servers in config.toml. Use ~/.codex/config.toml for a personal server and .codex/config.toml for a trusted-project dependency. The desktop app, CLI, and IDE extension share this configuration; ChatGPT web does not read local config and instead uses installed plugins/connectors.

For a local STDIO server:

[mcp_servers.example]
command = "example-mcp"
args = ["--stdio"]
cwd = "/path/to/server"
env_vars = ["EXAMPLE_TOKEN"]

For remote HTTP, configure the documented URL and authentication fields for the server. Prefer OAuth or a platform credential boundary; do not commit tokens. Use codex mcp add, codex mcp list, and codex mcp login for installation, inspection, and OAuth where appropriate.

An MCP server’s own instructions should state cross-tool workflows, constraints, and rate limits, with the first 512 characters self-contained for tool-selection decisions. A skill can add the task procedure and declare the dependency in agents/openai.yaml.

Review every tool independently

For each tool record:

  • purpose, owner, and data classification;
  • input and output schema, including untrusted-content handling;
  • authentication and credential injection;
  • read and write authority;
  • filesystem, network, and external-system boundaries;
  • approval and audit behavior;
  • timeout, retry, idempotency, pagination, and rate limits;
  • concise-output and artifact behavior;
  • disable, revoke, and incident procedures.

A shell sandbox constrains that shell tool, not an unrelated MCP tool. Likewise, a skill’s selection does not confer permission, and a hook around one tool path does not govern equivalent actions through another server.

Network and secrets

Treat skills plus open network access as a high-risk exfiltration path. Apply two allowlists: an organization maximum and a smaller task-specific destination set. Bind secrets to the intended domain or tool boundary and inject them without exposing raw values to the model. Treat tool output and remote content as untrusted input that may contain prompt injection.

Public or untrusted CI inputs need trusted triggers or explicit approval, sanitized prompt data, least-privileged credentials, and deterministic preparation before any write-capable agent step.

In OpenAI hosted shell, the organisation allowlist is the maximum and the request network_policy must be a subset. domain_secrets exposes placeholders to the model while a sidecar injects credentials only for an approved destination. Preserve the same outcome in other runtimes even when their configuration names differ.

When to use subagents

Use subagents when independent tasks can run concurrently or when high-volume exploration should be isolated from the main context. Good examples are separate security, test, dependency, and documentation reviews; independent package exploration; or a bounded research task that returns a concise report.

Do not delegate tightly coupled edits, ambiguous ownership, or work that needs continuous shared decisions. Each subagent performs its own model and tool work, so parallelism multiplies token and tool cost.

Every delegated task should specify:

  • one bounded objective and output format;
  • allowed files or systems;
  • read-only versus write authority;
  • validation and stop conditions;
  • what evidence to return to the main task;
  • whether it may create further subagents.

Use separate worktrees when independent agents will write. A shared context is not a substitute for filesystem isolation.

Custom agent profiles

Codex project .codex/config.toml can define agent roles with specialized instructions, models, reasoning effort, and tool configuration. Use higher reasoning for complex reviewers or security analysis and lower effort for straightforward mechanical tasks. Default nesting depth permits direct child agents but not arbitrary recursive teams; keep deeper delegation an explicit design choice.

Anthropic supports specialized subagents and plugin-provided agents with their own prompts and tool constraints. Do not assume the profile formats or tool inheritance are portable; standardize the role contract and evidence, then map it to each client.

Choose the runtime integration

  • Local CLI or script: use for one bounded operation or a shared human/CI command. Define stdout, stderr, exit code, and artifacts.
  • Non-interactive Codex or Claude invocation: use for CI or a scheduled agent task. Define a machine-readable result, permissions, and timeout.
  • Agent SDK: use when an application embeds and orchestrates agents. Define typed calls, state, traces, and cancellation.
  • MCP server: use when another agent or client should call the capability as a tool. Define schemas, authentication, and tool-level policy.
  • App Server or event runtime: use when interactive clients need streaming, approvals, reconnects, and durable threads. Define thread, turn, and item events plus capability and version negotiation.

Do not parse an interactive terminal when an SDK or event protocol owns the lifecycle. Do not introduce a long-lived server when an exit status and artifact are enough.

Local and hosted shell can share a workflow contract: a local host executes the requested shell call and returns its structured output, while a hosted container owns execution. In either case, declare an artifact boundary so tools write durable outputs, models reason over them, and later steps or humans can retrieve them without depending on transcript state.

Sources: OpenAI MCP, OpenAI customization, OpenAI subagents, OpenAI shell guidance, and OpenAI App Server.