MCP vs REST API: which architecture should you choose for AI agents?
MCP or REST API for an AI agent? Choose based on who picks the operation: the code, the model, or both in a hybrid architecture.
10 min read
Before the list: three rules
Fewer servers, better cadence. Every server adds tools to the model’s context and decisions to its plan. Ten well-chosen tools beat sixty. Start with two servers, add one when a workflow clearly needs it.
Read first, write behind approval. Most of the value of MCP for a coding assistant is context: the issue, the failing test, the production error, the decision that explains the odd constraint. Reads are cheap to allow. Allow one write at a time, reversible, behind an approval prompt, and watch the logs before allowing the next.
One identity per server. Claude Code acts as you. Give it a token scoped to what you would do yourself in that system, and revoke it as easily. A server that only accepts a broad admin token is not ready for an agent.
The servers, in the order to add them
1. Your repository host
The first server for any coding agent: issues, pull requests, reviews, CI status. GitHub publishes an official MCP server; GitLab and others have community or official equivalents. Allow: read issues and PRs, read CI results, comment. Hold back: merge, force-push, delete.
2. Documentation, versioned
A documentation server lets the model read the current docs of the libraries you use instead of relying on training data that may be a major version behind. Context7 is the common choice; some teams point a filesystem server at their own docs folder. Allow everything — it is read-only by nature.
3. The filesystem, scoped
The reference filesystem server gives the model a bounded view of a directory: useful when your work spans several repositories or a docs folder outside the current one. Scope it to the paths you would open yourself, never to your home directory.
4. A browser
A browser server (Playwright is the reference) turns “the button does not work” into something the agent can reproduce: open the page, click, read the console, take a screenshot. Allow navigation and reading; be careful with anything that submits forms on real sites.
5. Your database, read-only
A Postgres or SQLite server with a read-only role answers the questions that otherwise cost a round trip to a colleague: what does this table actually contain, which rows hit this constraint, how many users are in this state. Use a role that cannot write. Ever.
6. Error tracking
A Sentry-style server lets the agent read the stack trace, the breadcrumbs and the frequency of the error it is fixing, and link the fix to the issue. Read-only is plenty.
7. Your project tool
This is where the agent learns why it is doing the work: the card, the acceptance criteria, the linked documents, the decision that rules out the obvious approach. It is also where the result should land — a comment, a status change, a question for the reviewer — instead of staying in a chat window.
Stellary’s server exposes projects, cards, documents, missions and approvals through MCP, with an identity per agent, a tool allowlist and an autonomy policy (direct, supervised, proposal). The Claude Code guide shows the three-step configuration. Linear, Notion and Jira have MCP servers too; the criteria are the same — can the agent read the card and its context, and can its writes be put behind approval.
8. Design files
A Figma server lets the agent read the frame it is implementing: dimensions, tokens, text. Read-only, and worth it for front-end work.
9. Your chat tool
Slack or equivalent, for reading the thread where the requirement was actually discussed. Read-only; never let an agent post to a channel without a person in the loop.
10. A search server
Web search fills the gap between documentation and the error message nobody documented. Keep it last: it is the server that most often sends the model down a rabbit hole.
What a good first day looks like
Connect the repository host and the project tool, both read-only. Ask Claude Code to prepare a change: read the card, read the linked issue, read the failing test, propose a plan. Approve the plan, let it implement, run the tests. Then allow one write: a comment on the card with the result and the evidence. When that has worked ten times, consider allowing a status change behind approval. That is the rollout pattern described in what MCP changes for AI coding tools, and it is the difference between an assistant that helps and an agent you trust.
Security questions to ask any server
- Under which identity does it act, and can I scope it to one project or repository?
- Which tools write, and can each write be put behind approval?
- Is there an audit trail I can read afterwards?
- What happens on a timeout, an expired token, a missing resource — an error, or a silent partial success?
- Does the server follow the MCP authorization guidance, or does it want a long-lived admin token?
FAQ
Which MCP servers should I connect to Claude Code first?
Your repository host and your project tool, both read-only. They give the agent the issue, the acceptance criteria and the context that explains the constraints. Add a documentation server next, then a browser or a read-only database when a workflow needs it.
How many MCP servers is too many?
When the model starts choosing the wrong tool or ignoring the right one. Every server adds tools to its context and decisions to its plan. Two or three well-scoped servers usually beat ten; add one when a workflow clearly needs it and remove the ones nobody uses.
Can Claude Code update my project management tool through MCP?
Yes, if the server exposes write tools and you allow them. Start with a comment on the card (the result and the evidence), behind an approval prompt. Stellary’s server puts every non-read action behind a per-agent policy: direct, supervised or proposal-only.
