Connect an MCP-aware coding agent

Tenchi's MCP server gives a coding agent structured access to the application map, route table, registered application-tool contract, architecture diagnostics, generator previews, OpenAPI and tool compatibility, deployment preflight, operational-task discovery, and the complete validation loop. Inspection and preview tools do not edit application files; check runs the project's own validation commands and can have their usual side effects.

New applications include the required development dependency and a project-local .mcp.json. After uv sync, an MCP client that recognizes this file can start the server with no additional Tenchi configuration.

Add MCP to an existing application

Install the optional dependency:

uv add --dev "tenchi[mcp]"

Create .mcp.json at the application root:

{
  "mcpServers": {
    "tenchi": {
      "command": "uv",
      "args": ["run", "tenchi", "mcp", "--root", "."]
    }
  }
}

If your client does not read project-local MCP configuration, register the same command and arguments through that client's MCP settings. The server uses stdio; starting tenchi mcp directly leaves it waiting for an MCP client on standard input.

Give the agent project context

The tenchi://project/agents resource contains the application's AGENTS.md. Ask the agent to read it before changing code. If the file is absent, the resource supplies a short fallback workflow and a link to the full coding-agent guide.

The server captures one application root when it starts. Every tool operates inside that root, and OpenAPI and application-tool snapshot paths cannot escape it. Inspection tools reload the application's source for each call, so a server that stays open sees edits made during the agent session.

Use the tools

task_run is absent by default. Start the server with --allow-task-runs to expose it:

uv run tenchi mcp --allow-task-runs

The tool can change application state and uses the credentials available to the MCP server process. Only enable it for an agent and environment authorized to perform operational work. See Operational tasks for the complete workflow.

preflight is available by default and is marked read-only. It still contacts the environment selected by the MCP server process. Call it only when that process has the intended deployment configuration and read-only dependency credentials. See deployment preflight for the application-side contract and redaction boundary.

Every tool returns structured content with a schema_version. A doctor finding, failed check, generator conflict, or incompatible API or tool contract is a valid result with ok: false or compatible: false; malformed arguments and unreadable or unsafe paths are MCP errors. Tenchi snapshots every tool's input and output schema in CI; breaking or unknown changes require a new protocol version.

Follow the agent loop

For a feature change, give the agent this sequence:

1. Read tenchi://project/agents.
2. Call app_map with the feature name and inspect diagnostics and unresolved relationships.
3. Call make_preview when new framework-shaped files are needed.
4. Edit ordinary Python files through the agent's normal filesystem tools.
5. Call check and resolve every failed step.
6. Call openapi_diff before accepting a changed OpenAPI snapshot.
7. Call tools_diff before accepting a changed application-tool snapshot.
8. Call verify with the pull request base, previous push, or previous release and retain its completion receipt.

The agent must still make route and infrastructure wiring explicit in the application source. MCP previews follow the same rule as tenchi make: they describe the remaining wiring instead of silently changing composition files.

Override application conventions

The generated structure works with the defaults. For an application using different module targets or snapshot location, change the registered command:

uv run tenchi mcp \
  --root . \
  --routes my_app.server.routes:routes \
  --api-routes my_app.server.routes:api_routes \
  --preflight my_app.server.preflight:checks \
  --tasks my_app.server.tasks:runner \
  --jobs my_app.server.jobs:jobs \
  --tools my_app.server.tools:tools \
  --snapshot api/openapi.json \
  --tool-snapshot api/tools.json \
  --title "My API" \
  --version 1.0.0

routes uses --routes. The map, OpenAPI diff, check, and verify tools use --api-routes; preflight uses --preflight; the task tools use --tasks. The map loads registered background jobs through --jobs and registered application tools through --tools. Tool discovery and compatibility also use --tools; tools_diff, check, and verify use --tool-snapshot. OpenAPI title, version, description, and security defaults come from the same literal route-module declarations used by tenchi check. --title, --version, --description, and --security provide the same explicit overrides when an application does not keep that metadata as literals.

Continue with coding agents for the complete source-editing workflow or the CLI reference when an agent can run shell commands but not MCP.