AI Coding Tools and MCP

This sheet explains roles of tools, reusable instructions, coding agents, and integration protocols. Exact product capabilities and CLI flags change; consult the linked live vendor documentation for the installed version before relying on a command or setting.

For an end-to-end plugin and subagent task contract, continue with AI Agents, Plugins, and Subagents. For a concrete package, use Build an AI Plugin; for review quality and Jira workflow integration, use Define a Code Review Agent and Connect Jira to AI Workflows Across the SDLC. For a local assistant whose privacy claim can be tested, use Build a Private Local AI Assistant.

Agent vs tool vs skill vs workflow vs MCP

Item	Responsibility	Example	Does it itself authorize an action?
Coding agent	Plans/executes a bounded engineering goal through a model loop	Diagnose a Swift test failure	No; permissions come from the host/tool policy
Tool	Performs a narrow action with validated input/output	Search source, run an allowed test	Tool broker must enforce access and validation
Skill	Reusable instructions and domain procedure, optionally with resources/scripts	Security review checklist	No; it guides the agent but is not an access control
Workflow	Deterministic task sequence with gates/branches	Plan → implement → test → review	Only the workflow's external permission system grants access
MCP	Open protocol for AI applications to connect with external context/tools	A server exposes search or a database query	No; discovery/connection does not equal safe authorization
Orchestrator	Plans, budgets, routes, gates, and integrates agent/tool work	Supervisor with scoped workers	Must still enforce each capability outside the model

Claude Code

Claude Code documentation describes repository guidance with CLAUDE.md, specialized subagents with their own context/prompts and configurable tool access, and reusable skills/integrations. Project/user/managed configuration scopes and current capabilities should be checked in the official docs because names, discovery, permission behavior, and version requirements evolve.

Practical use:

Keep CLAUDE.md concise: setup, architecture map, test commands actually present in the repo, code conventions, and safety constraints.
Delegate read-only exploration or a genuinely isolated specialty review when that keeps logs/search results out of the main context.
Restrict tools for review agents; assign non-overlapping file ownership for edits.
Review the subagent definition and effective permissions, not just its prompt.
Validate all modifications with the repository’s own tests and inspect the final diff.

An agent's separate context can control context growth but does not mean zero cost or automatic correctness. A subagent that has write access may still change files; the parent must inspect them.

OpenAI Codex

Codex documentation describes AGENTS.md as a project-instruction mechanism, including layered instructions along the workspace path. The product documentation also describes separate surfaces for CLI, IDE, desktop, cloud, skills, MCP, and subagent-related capabilities; availability and exact interactions depend on the current surface, configuration, and session.

Practical use:

Place repository-wide rules in the root guidance and specialized rules near their owning code.
Keep instructions actionable: how to build/test, ownership boundaries, and what not to do.
Avoid copying generated instructions into every directory; review nested overrides for conflicts.
Use separate task/worktree boundaries for independent file edits where the selected Codex surface supports them.
Review tool permissions, changed files, test results, and any external side effects before accepting work.

Do not infer that a feature described for Codex CLI is available in Codex desktop or cloud, or vice versa. Consult the specific current product documentation linked below before using a command, config field, or agent feature.

Model Context Protocol (MCP)

MCP is an open protocol for connecting AI applications with external data and capabilities. The host application contains an MCP client; the client communicates with a server. A server can expose:

Primitive	Typical control	Example	Risk to manage
Prompts	User/application selects template	Code-review prompt	Prompt content can be stale or overly privileged
Resources	Application attaches contextual data	Project file, API documentation	ACL, prompt injection, data size and freshness
Tools	Model may request a function call	Search issue tracker, create draft	Side effects, auth scope, input validation, approval

The host normally mediates what server is connected, which resources enter context, and whether a tool call is approved/executed. MCP standardizes the interaction contract; it does not secure a poorly designed server or make untrusted output safe.

Before adding an MCP server, verify its publisher, transport, authentication, requested scopes, tool surface, data retention, network destinations, and update process. Prefer read-only narrow tools first. Separate credentials by user and server; do not place tokens in prompts or source. Validate tool results as untrusted data and show approval details for consequential writes. Review the current specification's authorization and security sections because protocol revisions change.

User → AI host (policy, approvals, UI)
           ├── model proposes tool request
           └── MCP client ── protocol/transport ──> MCP server
                                                   ├── tool handler
                                                   ├── resource provider
                                                   └── prompt templates

Token-efficient, secure coding workflow

1. Clarify acceptance + inspect status/instructions
2. Search symbols and read bounded context
3. Propose architecture/contract and identify risk
4. Assign one owner per write path; review tasks are read-only
5. Implement with scoped tools and no unnecessary network access
6. Run targeted tests, then required broader checks
7. Independent review checks diff + evidence, not model confidence
8. Integrator resolves findings, updates docs, reports limitations

For a SwiftUI feature that calls a backend, an architecture reviewer can define request/state/error contracts; an iOS worker owns one feature slice; a backend reviewer checks API semantics; a security reviewer assesses token/data boundaries read-only; a test worker proposes coverage only after the contract is stable; and one integrator validates final behavior. Do not start all roles automatically. If one person can safely complete a small dependent change in one context, delegation adds cost with little benefit.

Use an explicit task contract, small source package, acceptance checklist, and output containing changed paths/evidence/risks. A review should inspect the actual diff and rerun tests, since textual reports can be stale or incomplete. Separate “conceptual orchestration pseudocode” from vendor-supported product behavior.

const allowedReadTools = new Set(["searchSymbols", "readAssignedFile"]);

function validateProposedToolCall(call) {
  if (!allowedReadTools.has(call.name)) {
    throw new Error("Tool is outside this review task's allowlist");
  }
  return validateSchemaFor(call.name, call.arguments);
}

This is a small JavaScript policy sketch, not an MCP or vendor SDK function. The broker must perform the actual authorization and filesystem checks; validating a model-proposed name alone is not a security boundary.

set -eu
git diff --check
# Run the repository's documented, task-relevant test command after confirming it.

The shell snippet checks whitespace and fails on command errors; it does not run the test suite. Never infer a test command from an example without checking the project instructions/package scripts.