From API to AI Tool in 5 Minutes

Most teams that want to expose their APIs to AI agents end up writing the same thing: a thin wrapper that translates between an AI function-calling schema and an HTTP request. The wrapper duplicates the API definition, introduces another thing to maintain, and drifts from the real API over time. Then they write another one. And another.

The Model Context Protocol eliminates this pattern. MCP is a standard that lets AI agents discover and call external tools — and if your API is already defined somewhere (an OpenAPI spec, a Postman collection, a workflow you built last month), turning it into an MCP tool takes minutes, not days. This post is a practical walkthrough of that process end to end.

What You Will Have at the End

By the time you finish this walkthrough, you will have:

• An Apitide workflow built from an existing OpenAPI spec
• An MCP server that exposes selected workflow routes as tools
• A working connection in Claude Desktop — Claude can call your API
• OAuth authentication protecting the tools from unauthenticated access
• Per-tool execution logs in your Apitide analytics dashboard

The walkthrough uses a simple product catalogue API as an example, but the pattern applies to any API — internal microservices, third-party platforms, your own backend routes.

Step 1 — Import Your OpenAPI Spec

If you already have an Apitide workflow that covers the routes you want to expose, skip to step 2. If you are starting from an OpenAPI spec or Postman collection, the import process takes under a minute.

In the Apitide workflow builder, click Import Workflow and select OpenAPI Specification. Paste your spec or upload the file — both JSON and YAML are supported. Apitide reads the spec and generates one workflow route per operation, preserving the endpoint path, HTTP method, request parameters, request body schema, and response schemas.

The imported workflow already has all the schema information needed to generate MCP tool definitions. The route descriptions become the tool descriptions that the AI agent reads when deciding which tool to call. Clear, accurate descriptions in your OpenAPI spec directly improve how well the agent uses your tools.

Step 2 — Review and Configure Your Workflow Routes

After importing, review the generated routes. Each route has a trigger (the API endpoint trigger, which defines the HTTP method and path) and one HTTP connector step that calls your actual upstream API. The trigger is what the MCP tool will invoke; the HTTP step is what calls your real service.

At this point you can enrich the routes before exposing them as MCP tools. Common enrichments:

• Add authentication injection: Store your API credentials as a workflow variable and inject them as headers in the HTTP step. The AI agent never needs to know your API key — it calls the MCP tool, and Apitide handles authentication with your upstream service.
• Add response transformation: If your API returns more data than the AI agent needs, add a JSONata transformation step to trim the response. Smaller responses are faster and cheaper for AI agents to process.
• Add parallel steps for composite operations: If “get product details” requires calling both a product service and an inventory service, configure the two calls to run in parallel and merge the responses. The AI agent sees a single tool call with a unified response.

None of these enrichments are required to expose the routes as MCP tools — you can start with the raw imported routes and improve them over time.

Step 3 — Create an MCP Server

Navigate to MCP Servers and click Generate MCP Server. Give the server a name and description — the description is what Claude will see when the user asks what this server can do.

In the route selector, choose the workflow routes you want to expose. You do not have to expose every route — only the operations that make sense for AI agent use. For a product catalogue, you might expose the GET endpoints (search, get by ID, list categories) but not the PUT and DELETE endpoints that modify data.

Tool naming is controlled by the include workflow name toggle. With it off, a route named get_products becomes an MCP tool called get_products. With it on, it becomes catalogue_get_products. The prefixed form is useful when you have multiple MCP servers connected simultaneously and need to disambiguate tool names.

Click Generate MCP Server. Apitide creates the server configuration, generates the MCP tool definitions from your route schemas, and assigns a unique server URL. The server is live immediately.

Step 4 — Create an API Key

Open the server you just created and navigate to the API Keys tab. Click Add Key, give it a name (e.g. “Claude Desktop — dev”), and copy the generated key. The key is shown once — store it somewhere safe.

Each MCP server has its own isolated set of API keys. A key grants access only to the tools on that specific server — it cannot be used to access other MCP servers, the workflow builder, or the management API. If the key is compromised, revoke it from this tab and generate a replacement; other keys on the same server are unaffected.

Step 5 — Connect to Claude Desktop

On the server overview tab, find the connection snippet. It looks like this:

{
  "mcpServers": {
    "your-server-name": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.apitide.io/mcp/{storeId}/{serverSlug}",
        "--header",
        "X-API-Key: <your-api-key>"
      ]
    }
  }
}

Open Claude Desktop, go to Settings → Developer → Edit Config, and paste this snippet into your claude_desktop_config.json file. Replace <your-api-key> with the key you generated in step 4.

Restart Claude Desktop. The MCP server connects, Claude discovers the available tools, and you will see them listed in the tool panel. Ask Claude something like “search for running shoes under £50” — Claude selects the appropriate tool, calls it with the right parameters, and returns the results.

Adding OAuth Authentication (Optional but Recommended)

By default, tool access is controlled by the API key. For production deployments where tool calls execute on behalf of a specific user — reading their orders, updating their profile — you want to authenticate the user before any tool can be called. The MCP server's Authenticationtab lets you configure OAuth login.

The custom login form option is the most common choice for teams that already have their own authentication system. Point it at a workflow route that accepts a username and password, calls your auth service, and returns an access token. Apitide stores the token in the MCP session and forwards it as an Authorization header on every subsequent tool call — your upstream services receive authenticated requests without any changes.

When OAuth is enabled and a user connects Claude Desktop for the first time, they see a login form before any tools are available. After logging in, the session persists for the duration you configure (up to 30 days) — Claude does not prompt for re-authentication on every use.

Understanding What Claude Sees

It is worth understanding what the MCP protocol actually sends to Claude, because this determines how well Claude uses your tools. When Claude connects to your MCP server, it receives a list of tool definitions. Each definition contains:

Claude uses the tool description to decide when to use the tool, and the input schema to construct the call parameters. Two things make a large practical difference: the quality of your route descriptions, and the quality of your parameter descriptions. A route described as “Get products” is much less useful to Claude than “Search the product catalogue by keyword, price range, and category. Returns a list of matching products with name, price, SKU, and stock status.” Investing a few minutes in descriptions pays off immediately in how reliably Claude uses your tools.

Monitoring Tool Calls in Analytics

Every MCP tool call creates an execution record in your Apitide analytics dashboard — the same record that a regular HTTP API call produces. You can see exactly which tools were called, with what parameters, how long each call took, which upstream services were hit, and what was returned.

Use the MCP filter in the analytics view to see only AI agent traffic, separate from direct API calls. This is valuable when you need to understand usage patterns: which tools Claude calls most frequently, whether it is making redundant calls that could be avoided with better tool descriptions, or whether a specific tool is consistently slow because of a slow upstream service.

If a tool call fails — the upstream service returned an error, schema validation rejected a parameter, authentication failed — the execution timeline shows exactly where the failure occurred and what the error was. You diagnose AI agent issues the same way you debug regular API calls.

Common Mistakes and How to Avoid Them

Exposing too many tools at once. Each tool adds to the context Claude receives when it connects. A server with 50 tools is harder for Claude to navigate than one with 10 well-named tools. Start with the tools that cover the most common operations and add more as you understand how Claude uses them.

Vague tool descriptions. If two tools have similar descriptions, Claude may pick the wrong one. “List orders” and “Get orders” are easy to confuse. Be specific: “List all orders for the authenticated customer, sorted by date descending” vs “Get a single order by order ID, including line items and fulfilment status.”

Returning too much data. If a tool returns a large response — hundreds of fields, deeply nested objects — Claude spends tokens processing data it does not need. Add a transformation step that trims the response to the fields that matter for AI use cases. This makes calls faster and reduces the chance of Claude misinterpreting irrelevant fields.

Skipping schema validation. MCP sends the AI-supplied parameters directly to your workflow. If Claude constructs an invalid request, your upstream service receives it. Add request body schema validation to your workflow routes so that malformed requests fail fast with a clear error, rather than propagating to your backend.

What Comes Next

You now have a working MCP integration. A few directions to explore from here:

• Multiple MCP servers: Create separate servers for different domains — a commerce server, a CRM server, an analytics server — with different capability scopes and API key policies.
• Workflow-level AI generation: Use Apitide's AI workflow generation to scaffold new workflows from natural language descriptions, then expose them as MCP tools in minutes.
• Production OAuth: Configure the authentication tab with your production auth service so that tools execute on behalf of real authenticated users, with session expiry set to days or weeks rather than the default one hour.