Agent instructions and MCP

What it is and why it exists

An agent starts without the unwritten knowledge held by a repository’s maintainers. It can infer patterns from nearby files, but inference cannot reliably identify the canonical test command, generated directories, ownership boundaries, or a rule that an architecture test does not yet enforce. A versioned instruction file makes those expectations visible before the agent proposes a change.

AGENTS.md and CLAUDE.md are Markdown guidance files consumed by particular coding-agent hosts. They are not language standards, and their discovery rules are not interchangeable. The useful shared idea is to store stable, repository-specific facts near the code whose work they govern.

Instructions answer questions such as where a change belongs, which command verifies it, and what must not be edited. They influence model behavior through the context window . They do not grant or revoke operating-system permissions, so a sentence such as “never read .env” is guidance rather than a security control.

The Model Context Protocol (MCP) connects an AI application to servers that expose tools, resources, and prompts through structured messages. For tools, the server advertises a name, description, and input schema; a client can list those tools and send a tool call . MCP standardizes that exchange, while the application and server remain responsible for trust, authorization, and side effects.

These mechanisms solve different halves of the same failure. Without explicit instructions, an agent may follow a locally plausible but wrong convention. Without narrow tool contracts, the same agent may use a broad shell or database credential for a task that needed only one bounded read.

Guidance, contracts, and enforcement

Keep three layers separate when you design an agent integration:

A good repository uses all three where the risk warrants them. The guide tells the agent to change src/payments/ and run a named test; the tool accepts only a normalized path under that directory; the delivery gate checks the diff and test exit code. Repeating the same rule as prose at every layer is less useful than giving each layer a check it can actually perform.

You meet instruction files when a coding CLI or IDE opens a repository, and you meet MCP when that host connects to local or remote capabilities. MCP is useful beyond coding tools, but repository work makes the boundary easy to see: source reads, issue lookup, schema inspection, tests, and deployments have different data and authority requirements.

How it works

An agent host first discovers the instruction sources relevant to its current location or files. It puts their text into model context together with the user’s task and selected repository evidence. The exact order matters because broad and local guidance can overlap.

Codex builds an instruction chain from global guidance and project files from the repository root down to the current working directory. In each project directory it selects at most one recognized instruction file, with AGENTS.override.md taking precedence over AGENTS.md. Guidance closer to the working directory appears later in the chain.

Claude Code reads CLAUDE.md files and supports project, user, local, and managed scopes. It can load more-specific files from subdirectories when it works there. Claude Code does not treat AGENTS.md as its native project file, but a CLAUDE.md can import AGENTS.md so a team keeps shared rules in one place and adds product-specific details separately.

Do not invent a universal merge algorithm for every host. Record which products the repository supports, keep a small adapter file when names differ, and ask the running agent to report the instruction sources it actually loaded. A guide at the repository root has no effect if the current host never discovers it.

From instruction to evidence

Write a repository rule so a developer or a program can tell whether work followed it. Each important entry should identify a scope, an action or constraint, and observable evidence.

1. Name the directory, file pattern, package, or operation the rule governs.
2. State the required behavior with an exact path, command, or interface name.
3. Explain a surprising constraint briefly when its reason is not visible in code.
4. Name the check that demonstrates compliance and its working directory.
5. State what not to change only when the boundary is real and stable.
6. Move temporary task details into the current request instead of accumulating them in the repository guide.

“Keep the code clean” has no reviewable meaning. “For changes under src/payments/, run pnpm test:payments from the repository root; do not edit src/generated/” gives the agent a scope, command, location, and exclusion that a later gate can inspect.

The guide should point to canonical documentation rather than copy long architecture descriptions. Long, duplicated instructions consume context and go stale independently. If a rule applies only to one subtree, place it in the host’s supported scoped mechanism rather than making every task carry it.

From declaration to tool result

An MCP tool declaration is an API contract presented to the client and model. The name and description help selection; inputSchema describes accepted arguments; an optional outputSchema describes structured results. Discovery happens through tools/list, and invocation happens through tools/call.

Schema validation is the first check, not the last. A syntactically valid path may escape through .. or a symbolic link; a valid project identifier may belong to another tenant; a valid query may request more rows than the task needs. The executor must normalize arguments and apply resource-level authorization on every call.

The result should separate protocol failure from a tool-reported execution error. It should preserve enough structure for the host to identify status, resource, size, truncation, and retry safety. Free-form success prose can supplement those facts but should not replace them.

Tool descriptions are also untrusted input when they come from a server outside your control. They can influence model selection and may contain prompt injection . Clients should expose only trusted servers, show sensitive calls to the user, and never interpret descriptive annotations as permission.

Capability and approval boundaries

Design tools around domain operations rather than around unrestricted transports. read_source({ path }), run_payment_tests({ target }), and create_preview({ revision }) expose less accidental authority than shell({ command }) or http_request({ url, body }). Narrow tools also produce logs a reviewer can understand without reconstructing a command string.

Apply least privilege twice: expose only the tools needed for this agent, then restrict which resources each tool can reach for this caller. A read-only source browser should not inherit deployment credentials merely because both capabilities live on the same server process.

An approval gate fits an operation whose exact target or impact requires human judgment. The approval surface should show the tool, normalized arguments, destination, and expected side effects. Approval of one preview deployment should not become standing permission for every later deployment call.

Instructions can ask the agent to seek approval, but enforcement belongs in the host or server. The policy must deny or pause the call even if the model forgets the rule, an injected document contradicts it, or a different client connects to the same MCP server.

Examples

These Node examples isolate the control logic from any particular model SDK. They model Codex-style instruction discovery, convert repository guidance into a delivery check, and implement the core of a bounded MCP-style tool. Every output below comes from Node v24.14.0.

Resolving instructions for a target file

The first program represents a repository with a root AGENTS.md and a payments-specific AGENTS.override.md. Its resolver walks from the root toward the target’s directory and selects the override before the regular file at each level.

The payments target receives both broad repository expectations and the closer override. The search target receives only the root file because no recognized file exists on its directory path. This program demonstrates Codex discovery rules; it is not a substitute for Claude Code’s different loading behavior.

Real discovery also begins from a detected project root and current working directory, not an arbitrary target string. Test the actual launch location used by developers and automation. A correct file in the wrong directory is still inactive guidance.

Turning guidance into a delivery check

Natural-language instructions help the model choose work, but a deterministic gate should verify the parts a machine can know. This contract limits changed paths and records the two commands that must exit successfully.

const contract = {
  allowedRoots: ["src/payments/", "tests/payments/"],
  forbiddenSuffixes: [".snap"],
  requiredChecks: ["pnpm test:payments", "pnpm lint"],
};

function verifyChange(change) {
  const failures = [];
  for (const file of change.files) {
    if (!contract.allowedRoots.some((root) => file.startsWith(root))) {
      failures.push(`path outside scope: ${file}`);
    }
    if (contract.forbiddenSuffixes.some((suffix) => file.endsWith(suffix))) {
      failures.push(`generated file changed: ${file}`);
    }
  }
  for (const command of contract.requiredChecks) {
    const result = change.checks.find((check) => check.command === command);
    if (result === undefined || result.exitCode !== 0) {
      failures.push(`check not passed: ${command}`);
    }
  }
  return failures.length === 0 ? ["PASS"] : failures;
}

const changes = [
  {
    files: ["src/payments/refund.ts", "tests/payments/refund.test.ts"],
    checks: contract.requiredChecks.map((command) => ({ command, exitCode: 0 })),
  },
  {
    files: ["src/payments/refund.ts", "src/generated/schema.snap"],
    checks: [{ command: "pnpm test:payments", exitCode: 0 }],
  },
];

for (const [index, change] of changes.entries()) {
  console.log(`change ${index + 1}: ${verifyChange(change).join(" | ")}`);
}

change 1: PASS
change 2: path outside scope: src/generated/schema.snap | generated file changed: src/generated/schema.snap | check not passed: pnpm lint

The second change violates three independently reviewable conditions. The gate does not ask whether the agent remembers the instructions; it derives a verdict from changed paths, exact command identities, and exit codes. In production, obtain that evidence from the version-control and process layers rather than accepting a model-supplied object.

String prefixes are sufficient only for the normalized repository-relative paths assumed by this small example. Any gate that receives operating-system paths must resolve separators and symbolic links and then prove containment. The guide and the enforcement code should name the same scope without sharing an unsafe shortcut.

Exposing one scoped source tool

The final program declares one tool with input and output schemas, then implements its validation and result shape. It deliberately has no general file-read or shell parameter. The in-memory repository makes both calls reproducible.

import { posix } from "node:path";
const repository = new Map([
  ["src/config.ts", "export const port = 8080;\n"],
]);
const readSourceTool = {
  name: "read_source",
  description: "Read one UTF-8 TypeScript source file under src/.",
  inputSchema: {
    type: "object",
    properties: { path: { type: "string" } },
    required: ["path"],
    additionalProperties: false,
  },
  outputSchema: {
    type: "object",
    properties: { path: { type: "string" }, bytes: { type: "integer" } },
    required: ["path", "bytes"],
  },
};
function readSource(arguments_) {
  const raw = arguments_?.path;
  if (typeof raw !== "string" || Object.keys(arguments_).length !== 1) {
    return { isError: true, message: "invalid arguments" };
  }
  const path = posix.normalize(raw);
  if (posix.isAbsolute(path) || !path.startsWith("src/") || !path.endsWith(".ts")) {
    return { isError: true, message: "path outside source scope" };
  }
  const text = repository.get(path);
  if (text === undefined) return { isError: true, message: "source not found" };
  return {
    isError: false,
    content: [{ type: "text", text }],
    structuredContent: { path, bytes: Buffer.byteLength(text) },
  };
}
console.log(`${readSourceTool.name}: ${readSourceTool.description}`);
for (const request of [{ path: "src/config.ts" }, { path: "src/../secrets/token.txt" }]) {
  console.log(JSON.stringify(readSource(request)));
}

read_source: Read one UTF-8 TypeScript source file under src/.
{"isError":false,"content":[{"type":"text","text":"export const port = 8080;\n"}],"structuredContent":{"path":"src/config.ts","bytes":26}}
{"isError":true,"message":"path outside source scope"}

Normalization turns the second argument into secrets/token.txt, which fails the src/ boundary. The declaration guides selection, while the handler repeats the check before reading. A real MCP server would connect this handler to its SDK and transport, then authorize the authenticated caller and resolve real paths safely.

The successful result supplies model-readable text and structured metadata. An output schema makes the metadata checkable, but it does not make the text trustworthy. A client should still treat file contents as untrusted repository data and cap the number of bytes it sends into model context.

Pitfalls

Writing vague or contradictory guidance

Fix: name exact scopes, commands, paths, and acceptance evidence. Periodically launch each supported agent from representative directories, list the loaded sources, and remove stale or duplicated rules. Put a short reason beside a non-obvious constraint so future maintainers know when it can change.

Assuming one filename has universal semantics

Fix: document the supported hosts and verify each product’s current discovery behavior. Keep shared guidance canonical, then use a small CLAUDE.md import or another documented adapter where needed. Ask the session to name active instruction sources before risky work.

Treating instructions as a permission boundary

Fix: remove unnecessary credentials and network routes, enforce authorization per operation, and require an approval gate for sensitive targets. Test that a forbidden call fails even when it is structurally valid and confidently explained by the model.

Publishing a universal MCP tool

Fix: publish task-shaped tools with typed fields, bounded results, and explicit side effects. Separate read, mutation, and deployment capabilities, and expose only the subset required in the current session. Keep free-form shell access behind a stricter policy when it cannot be removed.

Stopping at JSON Schema validation

Fix: normalize and authorize resources on every call, impose size and time limits, sanitize outputs, and record an idempotency or resource-version condition for retryable mutations. Test semantic edge cases separately from malformed JSON.

Returning secrets as tool context

Fix: select and redact output fields at the server boundary, cap result size, and return artifact references when raw data need not enter context. Log metadata and denial reasons without echoing secret argument values. Treat tool output minimization as part of the contract.

Further reading

• OpenAI Docs: custom instructions with AGENTS.md
• Claude Code Docs: CLAUDE.md and project memory
• Model Context Protocol: architecture overview
• Model Context Protocol specification: tools
• Model Context Protocol: security best practices