From API Mirrors to Intention-Based Tools
The first wave of Model Context Protocol (MCP) servers often mimicked existing REST APIs. Teams wrapped endpoints with minimal changes—a fast way to claim MCP support. It made sense at the time: repackaging well-understood interfaces was quicker than redesigning them.
The problem is that LLMs don't use tools the way developers use APIs. A developer writing code maintains state across calls: storing an ID from one response, checking a status before the next step, and wrapping each call in error handling. An LLM starts each conversation fresh. It has no memory of prior sessions, so it must rediscover available tools, their usage, and the correct sequence each time. With low-level wrappers, this leads to repeated orchestration errors and wasted tokens as the model re-solves the same coordination puzzles.
Why Workflows Beat Endpoints
MCP servers perform best when a tool maps to a complete user intention rather than a single API operation. A tool that handles an entire deployment end-to-end outperforms four tools that each cover a fragment of the pipeline.
Consider the contrast. An API-shaped server might expose separate tools for creating a project, adding a domain, and triggering a build:
create_project(name, repo)
add_environment_variables(project_id, variables)
create_deployment(project_id, branch)
add_domain(project_id, domain)
The LLM must call these in sequence, pass identifiers between calls, and handle possible failures at each juncture. This is exactly the kind of stateful coordination that causes models to struggle.
An intention-based alternative wraps the entire process in a single deploy_project call:
deploy_project(repo_url, domain, environment_variables, branch="main")
This tool handles sequencing, error recovery, and state management internally in deterministic code. The LLM receives a conversational summary—"Project deployed at example.com. Build completed in 45s."—instead of a raw JSON payload with status codes and nested objects.
Thinking about MCP tools this way should shift the design calculus:
API-shaped tools | Intention-based tools |
|
|
Multiple calls with state management | Single atomic operation |
Returns technical status codes | Returns conversational updates |
LLM assembles the workflow | Tool owns the complete process |
Designing Workflow-Centric MCP Servers
Start by walking through real user requests manually using your existing API surface. Pick a task like "set up my project with authentication and a database" and trace the steps. The parts that feel tedious, repetitive, or error-prone are the candidates for consolidation into a single MCP tool.
Treat MCP tools as tailored helper interfaces for an AI goal, not as projections of your API. Multiple endpoints and underlying business logic may sit behind one tool. If a person thinks of something as one workflow, expose it as one tool.
A well-structured workflow tool follows a specific pattern:
server.tool(
"deploy_project",
"Deploy a project with environment variables and custom domain",
{
repo_url: z.string(),
domain: z.string(),
environment_variables: z.record(z.string()),
branch: z.string().default("main")
},
async ({ repo_url, domain, environment_variables, branch }) => {
// Handle the complete workflow internally
const project = await createProject(repo_url, branch);
await addEnvironmentVariables(project.id, environment_variables);
const deployment = await deployProject(project.id);
await addCustomDomain(project.id, domain);
return {
content: [{
type: "text",
text: `Project deployed successfully at ${domain}. Build completed in ${deployment.duration}s.`
}]
};
}
);
Keep deterministic logic—API sequencing, retries, state persistence—in regular code. Reserve the LLM for steps that genuinely need reasoning or language interpretation. Test with real workflows; if a model makes multiple attempts or asks follow-up questions, that is a signal to refine the tool boundary.
Results and Takeaways
Teams that moved from API-shaped to workflow-shaped tools report improved reliability and efficiency. The common features of their designs:
- Tools centered on user goals rather than endpoint coverage
- Complete workflows exposed as single operations
- Conversational responses instead of technical status output
MCP performs best when tools mirror human intentions, not API reference pages. Because LLMs cannot hold state across sessions the way programs do, designing tools around complete workflows yields more dependable outcomes with less orchestration friction.
