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
An AI assistant cannot answer a project-specific question reliably if it only sees the latest chat message. It needs relevant project evidence: current work, goals, decisions, documents, dependencies, permissions, and recent changes.
More context is not automatically better. Useful context must be relevant, current, authorized, attributable, and small enough to interpret correctly.
What “Context” Actually Means
Several different systems are often grouped under one word:
- Prompt context — instructions and information included in the current model request;
- Retrieved context — cards, documents, comments, decisions, or metrics fetched for a specific question;
- Conversation state — earlier turns retained by the host application;
- Operational memory — approved facts or preferences saved for reuse across sessions;
- Tool results — live data returned after an API or MCP call;
- Model training — changes to model parameters during pretraining or fine-tuning.
These are not interchangeable. Logging a project decision does not automatically become model training data. More commonly, the decision remains in the project system and is retrieved at runtime when relevant.
That distinction matters for accuracy, privacy, retention, and user expectations.
Why Generic Answers Happen
Ask “What should we prioritize?” without project evidence and the model can only provide general principles. A useful answer requires facts such as:
- the current objective and deadline;
- active work and accountable owners;
- dependencies and blockers;
- customer, technical, or compliance constraints;
- earlier decisions and their rationale;
- available capacity and explicit commitments.
Even with those facts, the model should not present a recommendation as an objective truth. Prioritization includes judgment about value, risk, and strategy that may not be fully represented in the system.
The Five Qualities of Good Project Context
1. Relevance
Retrieve evidence related to the current project, objective, and question. A whole workspace dump increases noise and the chance that the model uses an unrelated fact.
2. Freshness
Show when a card, document, metric, or decision was last updated. A polished answer grounded in an obsolete specification is worse than an explicit “current information is missing.”
3. Authority
Not every source has equal weight. An approved architecture decision should outweigh an old chat suggestion. A live board state should outweigh a copied status report from last month.
4. Attribution
Important statements should link back to the card, document, comment, decision, or run that supports them. Attribution lets the user verify the answer and correct the source of truth.
5. Access control
Context must be filtered before it reaches the model. The connected identity, project membership, document permissions, token scopes, and agent rules should determine what can be retrieved.
A Practical Context Model
Current delivery state
The board provides cards, status, ownership, labels, due dates, dependencies, comments, and recent movements. This supports questions about what is active or blocked.
Goals and priorities
An assistant needs the stated outcome, not just the list of tasks. Otherwise it may optimize for clearing cards instead of delivering the intended value.
Documents and decisions
Specifications, design notes, meeting outcomes, and decision records explain why the work looks the way it does. Keep them close to delivery and show review or update dates.
Runtime evidence
Agent missions, pipeline runs, errors, proposals, and approvals reveal what has actually happened. An “agent completed” status is weak evidence if no result reached the project.
Team and policy context
Roles, permissions, tool access, autonomy mode, and escalation rules shape which action is appropriate. They should not be inferred from job titles or activity patterns.
How a Context-Aware Answer Is Produced
A reliable workflow looks like this:
- Resolve identity and scope — determine the user or agent, workspace, project, and permissions.
- Interpret the request — identify the decision, artifact, or action being requested.
- Retrieve candidate evidence — query the relevant board, documents, decisions, and runtime state.
- Rank and compress — keep the most useful evidence while preserving links and timestamps.
- Generate with boundaries — separate facts, inferences, missing context, and recommendations.
- Request approval or execute — apply the policy associated with the identity and action.
- Record the result — return changes, errors, and decisions to the source of truth.
Skipping the first or final step creates serious problems: unauthorized context may reach the model, or an apparently completed workflow may never update the project.
Examples
Status question
Weak: “The project appears to be progressing, but you should monitor blockers.”
Grounded: “Release validation is waiting on card SP-47. Its linked pipeline failed today, and no retry is recorded. The release owner is Alex.”
The second answer is useful only if each claim links to the current card, run, and owner record.
Decision retrieval
Weak: “Consider the trade-offs between Redis and Memcached.”
Grounded: “Decision ADR-14 selected Redis for multi-data-type support. The new requirement appears related, but ADR-14 was last reviewed six months ago. Confirm that its constraints still apply.”
The assistant retrieves precedent without pretending the earlier decision automatically settles the new one.
Risk signal
Weak: “Alice may be overloaded.”
Grounded: “Alice owns four active cards, including two due this week. Capacity data is not available, so workload risk cannot be confirmed.”
This avoids turning card count into a performance or availability judgment.
MCP and Project Context
The Model Context Protocol gives compatible AI hosts a standard way to discover tools, resources, and prompts exposed by a server. A project server can use MCP to return live, structured data and to offer scoped actions.
MCP does not send “everything the AI needs” automatically. The host decides which capabilities to use, the server authorizes each request, and clients differ in transport and feature support. See the MCP integration guide for Stellary's identity and permission model.
Context Risks
Stale or conflicting sources
Two documents may disagree, or a decision may have been superseded without a clear marker. The assistant should expose the conflict rather than quietly choosing one source.
Excessive retrieval
Large context windows do not remove the need for selection. Excessive context can bury the decisive fact, increase cost, and expose data unrelated to the task.
Prompt injection
Documents, comments, websites, and tool results are untrusted inputs. Content inside them should not override system policy, permissions, or the user's request.
Sensitive inference
Do not infer individual performance, health, availability, or intent from activity traces. Project context should support coordination, not covert monitoring.
Memory without governance
Saved context needs an owner, retention policy, edit path, and clear scope. A remembered preference can become wrong; a project-specific rule can become dangerous when reused elsewhere.
How to Improve Context Quality
- Give each project a clear objective and accountable owner.
- Keep card status, ownership, and blockers current.
- Link decisions to the work they affect.
- Add review dates and owners to important documents.
- Use typed fields for facts that drive deterministic rules.
- Preserve source links in AI briefs and recommendations.
- Make missing context explicit instead of asking the model to fill gaps.
- Test retrieval with the permissions of real users and agents.
- Log corrections so the source data or retrieval logic can be improved.
What to Measure
Evaluate the context system, not the fluency of the answer:
- factual correction rate;
- percentage of important claims with a source;
- age of retrieved documents and decisions;
- retrieval of unauthorized or unrelated data;
- time required for a user to verify an answer;
- actions that fail because required context was missing;
- changes that successfully reached the system of record.
Context turns a general model into a project-aware assistant only when the surrounding system retrieves the right evidence, enforces access, exposes uncertainty, and closes the operational loop. For the broader operating model, read What Is AI Project Management?.
