Claude Code with MCP: architecture of a controlled development workflow

Most disappointments with coding agents share one cause: the agent knows too little about the project and is allowed too much in the system at the same time. This deep dive describes a workstation where both are reversed – plenty of context, tightly scoped permissions – and how the handover to review and pipeline stays clean.

1. What the setup should achieve

Three goals that reinforce each other: the agent should know the project reality instead of guessing plausibly. It should only be allowed to change what the task requires. And everything it produces should take the same route as hand-written code – through review, gates and pipeline.

What is described here using Claude Code applies analogously to other MCP-capable clients. The basics of the protocol are covered in the pillar article MCP in software development.

2. Context: the underrated foundation

Before any server is connected, the cheapest step pays off: write the project knowledge into the repository. An agent reads what is there – not what is in the wiki or in somebody's head.

• Project instructions in the repository: structure, conventions, permitted and forbidden dependencies, test strategy, definition of done.
• Architecture decisions as short, dated notes – why something is the way it is, not just that it is.
• Interface contracts as files, not as prose: OpenAPI, schemas, example messages.
• Examples of the style you want: one cleanly implemented use case says more than a page of prose.

3. Scoping the servers

Rather than as many servers as possible, a deliberately small set with clearly separated roles is advisable:

What is missing is notable: no production access, no permission administration, no deployment. Those actions run through the pipeline with their own approvals.

4. Configuration in the project

The server configuration belongs in the repository, not in a personal environment – then the whole team works against the same scope, and changes to it go through review:

{
  "mcpServers": {
    "project-platform": {
      "command": "<server-binary>",
      "args": ["--project", "erp-2026", "--env", "staging"],
      "env": { "PLATFORM_TOKEN": "${PLATFORM_TOKEN}" }
    },
    "project-context": {
      "command": "<server-binary>",
      "args": ["--repo", "erp-2026", "--read-only"]
    }
  }
}

Structure and available options differ by client and server; the current form is documented by the respective vendor. Two principles matter here: a limited scope, and credentials from the environment rather than from the file.

5. Staging approvals sensibly

A client that asks on every read teaches reflexive confirmation within a morning. What works:

• Reading within the approved scope: without asking.
• Writing to a working branch and staging: approval per tool and session.
• Anything with outward effect – pushing to other repositories, messages, network access – individually, with visible parameters.
• Irreversible actions should not be offered at all.

6. Day-to-day way of working

The practical difference between frustrating and productive work lies less in the tool than in how tasks are scoped:

1. Keep the task small. One domain slice per run, not “build the module”.
2. Pass the requirement along, including its identifier – so it ends up in the commit trailer later.
3. Plan first, then implement. A short plan before the change surfaces misunderstandings while they are still cheap.
4. Derive tests from the requirement, not from the freshly generated implementation.
5. Read it yourself. The diff is the result – not the agent's summary.

7. Handover to review and CI/CD

This is where the setup proves itself. Everything the agent produces takes the same route as any other change: branch, commit with a requirement reference, merge request, review by a second person, blocking quality gates, merge, pipeline.

Labelling substantial AI use on the change set makes sense – not as a vote of no confidence, but so the depth of review can be assessed later.

8. Logging

The client's session history is not a log: it lives locally, is volatile and cannot be analysed. What holds up is server-side logging – who called which tool with which parameters and when. For regulated environments that is the basis of any later answer.

9. Limits

• Context cost. Too many tools and resources degrade selection. Fewer, but precise.
• Maintenance. Every server is software with updates, dependencies and failure behaviour.
• Client differences. Not every client supports every protocol capability to the same extent – test before rolling out.
• No substitute for architecture. A well-connected agent accelerates implementation, not decisions.

Checklist: setting up the workstation

Conclusion

A productive agent workstation comes from better context and clear handovers, not from more permissions. The effort mostly goes into work that pays off anyway: writing down conventions, maintaining contracts, documenting decisions.

Once this setup exists, tools can be swapped without reconfiguring everything – because what matters lives in the project, not in the client.