--- title: "Best Practices for Mapping REST APIs to MCP Tools" description: "Learn how to map REST API endpoints to MCP tools effectively — naming conventions, parameter mapping, error handling, and pagination patterns for AI agent consumption." canonicalUrl: "https://zuplo.com/learning-center/mapping-rest-apis-to-mcp-tools" pageType: "learning-center" authors: "nate" tags: "Model Context Protocol, API Best Practices" image: "https://zuplo.com/og?text=Best%20Practices%20for%20Mapping%20REST%20APIs%20to%20MCP%20Tools" --- The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) gives AI agents a standardized way to discover and call your APIs as tools. Instead of crafting custom integrations for every LLM, you define your API once and MCP handles the rest -- agents can browse available operations, understand their parameters, and invoke them with structured inputs and outputs. But REST APIs and MCP tools come from different paradigms. REST is resource-oriented with URLs, HTTP methods, headers, and status codes. MCP tools are function-oriented with names, descriptions, and parameter schemas. Getting the mapping right determines whether an AI agent can use your API effectively or stumbles through confusing tool names and ambiguous parameters. This guide covers the practical patterns for turning REST endpoints into well-structured MCP tools that AI agents can actually work with. ## How MCP Tools Map to REST Endpoints Each MCP tool corresponds to a single API operation. When you generate MCP tools from an OpenAPI spec, the mapping works like this: | OpenAPI Field | MCP Tool Field | | ---------------------------- | -------------------------------- | | `operationId` | Tool `name` | | `summary` / `description` | Tool `description` | | Path, query, and body params | Tool `inputSchema` (JSON Schema) | | Response schema | Tool output | Here is an OpenAPI operation and its corresponding MCP tool definition side-by-side. **OpenAPI operation:** ```yaml paths: /users/{userId}: get: operationId: getUserById summary: Get a user by their unique ID parameters: - name: userId in: path required: true schema: type: string description: The unique identifier of the user responses: "200": description: The user object ``` **Resulting MCP tool:** ```json { "name": "getUserById", "description": "Get a user by their unique ID", "inputSchema": { "type": "object", "properties": { "userId": { "type": "string", "description": "The unique identifier of the user" } }, "required": ["userId"] } } ``` The mapping is direct. The quality of your MCP tools is a direct reflection of the quality of your OpenAPI spec. ## Naming Conventions AI agents use tool names to decide which tool to call. When an agent sees a list of 20 tools, it reads the names and descriptions to pick the right one. Clarity matters more than brevity. **Use action-oriented operationIds that describe exactly what the tool does:** - `listUsers` -- not `getUsers` or `users` - `createOrder` -- not `postOrder` or `newOrder` - `getInvoiceById` -- not `invoice` or `fetchInvoice` - `searchProducts` -- not `findProducts` or `queryProducts` - `deleteComment` -- not `removeComment` or `destroyComment` **Follow a consistent verb pattern:** | Action | Verb | Example | | -------- | -------- | -------------- | | List all | `list` | `listOrders` | | Get one | `get` | `getOrderById` | | Create | `create` | `createOrder` | | Update | `update` | `updateOrder` | | Delete | `delete` | `deleteOrder` | | Search | `search` | `searchOrders` | Avoid generic names like `handleRequest` or `processData`. If an agent cannot determine what a tool does from its name alone, the name is too vague. ## Parameter Mapping Best Practices Parameters are where the mapping gets nuanced. REST APIs spread parameters across path segments, query strings, headers, and request bodies. MCP tools flatten everything into a single `inputSchema` object. **Path parameters become required tool parameters.** A path like `/orders/{orderId}` produces a required `orderId` parameter. This is straightforward. **Query parameters become optional tool parameters.** Filters, sorting, and pagination controls map to optional fields: ```yaml parameters: - name: status in: query required: false schema: type: string enum: [pending, shipped, delivered, cancelled] description: Filter orders by status ``` Notice the `enum` values. This is critical for MCP tools. When an AI agent sees `enum: [pending, shipped, delivered, cancelled]`, it knows exactly which values are valid. Without the enum, the agent has to guess -- and it often guesses wrong. **Request body fields become tool parameters.** For simple request bodies, flatten the fields into the tool's input schema: ```yaml requestBody: content: application/json: schema: type: object required: [name, email] properties: name: type: string description: The full name of the user email: type: string format: email description: The user's email address role: type: string enum: [admin, editor, viewer] description: The user's role in the organization ``` Each property -- `name`, `email`, `role` -- becomes a top-level parameter in the MCP tool's input schema. The `required` array carries over directly. **Write descriptions for AI agents, not just humans.** Every parameter should have a description that explains what it does and what values are acceptable. Compare: - Bad: `description: "The ID"` - Good: `description: "The unique identifier of the order, e.g. ord_12345"` Including examples in descriptions helps agents construct valid requests. ## Handling Pagination Pagination is one of the trickiest parts of the REST-to-MCP mapping. AI agents are not browsers -- they cannot easily navigate through pages of results, keep track of cursors, or know when to stop fetching. There are three practical approaches: **1. Return all results for small datasets.** If the collection is small (under a few hundred items), skip pagination entirely. A `listTags` endpoint that returns 50 tags does not need pagination. Simpler is better for AI agents. **2. Provide a `limit` parameter with a sensible default.** For larger collections, let the agent control how many results it gets back: ```yaml parameters: - name: limit in: query schema: type: integer default: 20 maximum: 100 description: Maximum number of results to return (default 20, max 100) ``` A default of 20 keeps responses manageable. The agent can request more if needed. **3. Expose separate `list` and `search` tools.** Instead of making the agent paginate through all orders to find one, give it a dedicated search tool: - `listOrders` -- returns recent orders with a `limit` parameter - `searchOrders` -- takes a query string and returns matching orders This pattern works well because agents are good at describing what they are looking for but bad at iterating through pages. ## Error Responses When something goes wrong, the AI agent needs to understand what happened so it can retry, adjust parameters, or ask the user for help. Vague error messages like `"Something went wrong"` are useless to an agent. Use the [RFC 7807 Problem Details](https://www.rfc-editor.org/rfc/rfc7807) format for structured error responses: ```json { "type": "https://api.example.com/errors/validation-error", "title": "Validation Error", "status": 422, "detail": "The 'email' field must be a valid email address. Received: 'not-an-email'", "instance": "/users", "errors": [ { "field": "email", "message": "Must be a valid email address", "received": "not-an-email" } ] } ``` Key principles for agent-friendly errors: - **Include the field name** that caused the error - **Show the invalid value** the agent sent, so it can correct it - **Explain what is expected** -- format, range, or valid options - **Use consistent error structure** across all endpoints When an agent receives a clear error like `"The 'status' field must be one of: pending, shipped, delivered"`, it can fix the request and retry automatically. ## What to Expose (and What Not To) Not every REST endpoint should become an MCP tool. More tools means more confusion for the agent. Be deliberate about what you expose. **Good candidates for MCP tools:** - CRUD operations on core resources (`createUser`, `getUser`, `updateUser`) - Search and filtering (`searchOrders`, `listProductsByCategory`) - Key business actions (`submitInvoice`, `approveRequest`) - Status checks (`getOrderStatus`, `getSystemHealth`) **Skip these:** - **Admin and internal endpoints** -- agents should not manage users or configure system settings - **Bulk operations** -- endpoints that accept arrays of hundreds of items are hard for agents to construct correctly - **File uploads** -- binary data does not map to MCP tool parameters - **Webhook management** -- registering and managing webhooks is infrastructure, not something an agent needs - **Deprecated endpoints** -- do not expose tools that will stop working A focused set of 10-15 well-designed tools is far more useful than 100 tools where the agent cannot figure out which one to call. ## OpenAPI Best Practices for MCP Your OpenAPI spec is the source of truth for your MCP tool definitions. Every gap in the spec becomes a gap in the tool. Here is a checklist: **Every operation needs an `operationId`.** Without it, the tool has no name. Do not rely on auto-generated IDs -- they produce names like `get_users_userId` that agents struggle with. **Write descriptions for both humans and agents.** The `summary` should be a short one-liner. The `description` can include details about behavior, edge cases, and relationships to other endpoints: ```yaml summary: Search for products description: > Search the product catalog by keyword. Returns up to 50 results sorted by relevance. Use the 'category' parameter to narrow results to a specific product category. For browsing all products, use the listProducts operation instead. ``` **Use `examples` in your schemas.** Examples help agents understand what valid data looks like: ```yaml properties: email: type: string format: email example: "jane@example.com" amount: type: number minimum: 0 example: 29.99 ``` **Mark required versus optional clearly.** Agents need to know which parameters must be provided and which ones can be skipped. Always define the `required` array at the schema level. ## Example: Mapping a Todo API Here is a complete example showing an OpenAPI spec for a todo API and the resulting MCP tools. **OpenAPI spec:** ```json { "openapi": "3.1.0", "info": { "title": "Todo API", "version": "1.0.0" }, "paths": { "/todos": { "get": { "operationId": "listTodos", "summary": "List all todos", "description": "Returns all todo items, optionally filtered by completion status.", "parameters": [ { "name": "completed", "in": "query", "schema": { "type": "boolean" }, "description": "Filter by completion status. True for completed, false for incomplete." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 }, "description": "Maximum number of todos to return (default 20, max 100)" } ] }, "post": { "operationId": "createTodo", "summary": "Create a new todo", "description": "Creates a new todo item. The title is required.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string", "description": "The title of the todo item", "example": "Buy groceries" }, "priority": { "type": "string", "enum": ["low", "medium", "high"], "description": "Priority level of the todo" } } } } } } } }, "/todos/{todoId}": { "get": { "operationId": "getTodoById", "summary": "Get a todo by ID", "parameters": [ { "name": "todoId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the todo" } ] }, "patch": { "operationId": "updateTodo", "summary": "Update a todo", "description": "Updates an existing todo item. Only include fields you want to change.", "parameters": [ { "name": "todoId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the todo" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "completed": { "type": "boolean" }, "priority": { "type": "string", "enum": ["low", "medium", "high"] } } } } } } }, "delete": { "operationId": "deleteTodo", "summary": "Delete a todo", "parameters": [ { "name": "todoId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the todo to delete" } ] } } } } ``` **Resulting MCP tools:** | Tool Name | Description | Required Params | Optional Params | | ------------- | ----------------- | --------------- | -------------------------------- | | `listTodos` | List all todos | -- | `completed`, `limit` | | `createTodo` | Create a new todo | `title` | `priority` | | `getTodoById` | Get a todo by ID | `todoId` | -- | | `updateTodo` | Update a todo | `todoId` | `title`, `completed`, `priority` | | `deleteTodo` | Delete a todo | `todoId` | -- | Five clean tools with clear names, descriptive parameters, and obvious required versus optional fields. An AI agent can look at this list and immediately understand what each tool does and how to call it. ## Turn Your OpenAPI Spec into MCP Tools You do not need to build the mapping layer yourself. If you have an OpenAPI spec, Zuplo can [turn it into a fully functional MCP server](/learning-center/create-mcp-server-from-openapi) in minutes -- complete with authentication, rate limiting, and analytics. Your OpenAPI descriptions become tool descriptions. Your parameter schemas become input schemas. Your API is instantly ready for AI agent consumption. Start with a well-structured OpenAPI spec, follow the patterns in this guide, and the resulting MCP tools will be ones that AI agents can actually use.