Link to headingHow LLMs use APIs differently

The key difference is context and state management. When you write code, you keep track of information between API calls. You store the project ID from the create call, check deployment status before adding the domain, and wrap error handling around each step so failures don't break the entire process.

LLMs work differently. Each conversation starts fresh with no memory of previous conversations. While they can see tool results within the current conversation, they have to figure out the right sequence of tools to use based on what's available. When those tools are low-level API wrappers, the LLM has to orchestrate multiple calls and manage the complexity of chaining them together each time.

For example, take deploying a project with the Vercel API. A developer might write code like this:

// Traditional API usage: developer manages the sequence
const project = await client.projects.create({
  name: domain.replace(/\./g, '-'),
  gitRepository: { repo: repoUrl }
});
await client.projects.createProjectEnv({
  idOrName: project.id,
  upsert: 'true',
  requestBody: Object.entries(env).map(([key, value]) => ({
    key, value,
    target: ['production', 'preview', 'development'],
    type: 'encrypted'
  }))
});
const deployment = await client.deployments.createDeployment({
  requestBody: {
    name: project.name,
    target: 'production',
    gitSource: { type: 'github', repo: repo.replace('.git', ''), ref: 'main' }
  }
});
await client.projects.addProjectDomain({
  idOrName: project.id,
  requestBody: { domain: domain }
});

This approach involves nested configurations, ID management across calls, and parsing repository URLs. A developer will solve for this once and re-use. But an LLM faces this puzzle fresh each time, often getting the nesting wrong or forgetting required fields.

Link to headingSingle workflow tools vs multiple endpoints

The solution is building tools around complete user goals rather than API capabilities. Instead of four separate tools, create one deploy_project tool that handles the entire workflow internally.

This changes everything about tool design:

Consider the difference in practice. An API-shaped MCP server might expose these tools:

create_project(name, repo)
add_environment_variables(project_id, variables)
create_deployment(project_id, branch)
add_domain(project_id, domain)

The LLM has to call each tool in sequence, pass IDs between calls, and handle potential failures at each step.

An intention-based tool looks different:

deploy_project(repo_url, domain, environment_variables, branch="main")

This single tool handles the complete workflow internally and returns a conversational response. Instead of { status: 200, data: { id: "proj_123" } }, the LLM can respond with "Project deployed at example.com. Build completed in 45s. All systems running normally."

Link to headingDesigning workflow based MCP tools

Start by testing the workflow manually before writing any code. Take a real user request like "set up my project with authentication and a database" and walk through it step by step using your existing APIs. The parts that feel tedious or repetitive are good candidates for a single MCP tool.

Think of MCP tools as tailored toolkits that help an AI achieve a particular task, not as API mirrors. There may be multiple APIs and business logic behind a single MCP tool. If users think of something as one workflow, design it as one tool.

Here's how to structure a complete workflow tool:

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.`
      }]
    };
  }
);

Use plain code for the deterministic parts. Things like API sequencing, error recovery, and state management are better suited for regular programming. Only involve the LLM for parts that truly need reasoning or natural language processing.

Test with real scenarios. Run actual user workflows through your tools. When you see the LLM making multiple attempts or asking for clarification, that's feedback about your tool design. The goal is for complex workflows to succeed on the first try.

Link to headingPerformance improvements with workflow tools

Teams that have shifted from API shaped tools to workflow shaped tools have seen meaningful improvements in reliability and efficiency.

The common thread is how these tools are designed:

• They focus on user intentions rather than API coverage

• They handle complete workflows rather than exposing single operations

• They respond in a conversational way rather than returning technical codes

MCP works best when tools reflect complete user goals. LLMs do not manage state the way developers do, so building tools around workflows produces better results.

Give this approach a try. The MCP handler makes it straightforward to expose your application logic as workflow based MCP tools. Get started with the Next.js MCP template or explore the documentation.