Technical10 min read

How MCP to API Mapping Works

Deep dive into how MCP tools are mapped to API endpoints. Learn about field mappings, transformations, and how tool arguments become API payloads.

API to MCP Team

How MCP to API Mapping Works

The mapping system is the core of how MCP tools connect to your APIs. This guide explains how tool arguments are transformed into API requests.

Overview

When an AI assistant calls an MCP tool, the system needs to:

  1. Take the tool's input arguments
  2. Transform them into the format your API expects
  3. Call the API with the transformed data
  4. Return the API response to the AI assistant

This transformation is handled by mappings that connect tool fields to API fields.

The Mapping Process

Step 1: Tool Definition

First, you define an MCP tool with an input schema. For example: 

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City name"
    },
    "unit": {
      "type": "string",
      "description": "Temperature unit (celsius or fahrenheit)"
    }
  },
  "required": ["city"]
}

This defines what arguments the tool accepts.

Simplified Format Support

The admin panel supports a simplified format for defining tool input schemas, making it easier to get started. Instead of writing the full JSON Schema structure, you can use a simplified syntax:

Type-based simplified format: 

{
  "city": "string",
  "unit": "string",
  "temperature": "number"
}

Description-based simplified format: 

{
  "city": "The name of the city",
  "unit": "Temperature unit (celsius or fahrenheit)"
}

When you use the simplified format, the admin panel will automatically detect it and show a helpful message:

> ℹ️ Simplified format detected > Your schema will be automatically converted to full JSON Schema format. Found 3 parameters: city, unit, temperature

The system automatically converts simplified formats to full JSON Schema:

  • If the value is a valid JSON Schema type (string, number, integer, boolean, array, object), it uses that as the type
  • If the value is not a valid type, it treats it as a description and defaults to string type
  • All fields are automatically added to the required array

You can also click a button in the UI to convert the simplified format to full JSON Schema format immediately, giving you full control over the schema structure.

Step 2: API Configuration

You configure an API endpoint that expects a different format: 

{
  "location": "string",
  "temperature_unit": "string"
}

Notice the field names are different: city vs location, unit vs temperature_unit.

Step 3: Create the Mapping

The mapping connects these two formats:

  • Tool field: city → API field: location
  • Tool field: unit → API field: temperature_unit

Field Mappings

Field mappings define how each tool field maps to an API field. There are three types of transformations:

1. Direct Mapping

The simplest transformation - pass the value as-is:

  • Tool field: city
  • API field: location
  • Transformation: direct

Result: {city: "New York"} → {location: "New York"}

2. Constant Mapping

Use a fixed value regardless of tool input:

  • Tool field: (none)
  • API field: api_version
  • Transformation: constant
  • Value: "v1"

Result: API payload always includes {api_version: "v1"}

3. Expression Mapping

Transform the value using a JavaScript expression:

  • Tool field: temperature
  • API field: temp_celsius
  • Transformation: expression
  • Expression: value * 9/5 + 32 (convert Celsius to Fahrenheit)

Result: {temperature: 20} → {temp_celsius: 68}

Mapping Configuration Structure

A complete mapping configuration looks like this: 

{
  "field_mappings": [
    {
      "tool_field": "city",
      "api_field": "location",
      "transformation": "direct"
    },
    {
      "tool_field": "unit",
      "api_field": "temperature_unit",
      "transformation": "direct"
    },
    {
      "api_field": "api_version",
      "transformation": "constant",
      "value": "v1"
    },
    {
      "tool_field": "temp",
      "api_field": "temperature",
      "transformation": "expression",
      "expression": "value + 273.15"
    }
  ],
  "static_fields": {
    "source": "mcp",
    "timestamp": "auto"
  }
}

The Complete Flow

1. Tool Call

An AI assistant calls the tool: 

{
  "name": "get_weather",
  "arguments": {
    "city": "San Francisco",
    "unit": "celsius"
  }
}

2. Mapping Lookup

The system looks up the mapping for this tool and finds:

  • Tool get_weather → Mapping → API weather-api

3. Transformation

The transformer applies the mappings: 

// Input: {city: "San Francisco", unit: "celsius"}
// Mappings applied:
{
  location: "San Francisco",        // city → location (direct)
  temperature_unit: "celsius",      // unit → temperature_unit (direct)
  api_version: "v1",                // constant
  source: "mcp",                    // static field
  timestamp: "auto"                  // static field
}

4. API Call

The transformed payload is sent to the API: 

POST https://api.weather.com/v1/current
Headers: {...}
Body: {
  "location": "San Francisco",
  "temperature_unit": "celsius",
  "api_version": "v1",
  "source": "mcp",
  "timestamp": "auto"
}

5. Response Handling

The API response is returned to the AI assistant in MCP format: 

{
  "content": [
    {
      "type": "text",
      "text": "{\"temperature\": 18, \"condition\": \"sunny\"}"
    }
  ],
  "isError": false
}

Advanced Features

Static Fields

Add fields that are always included in the API payload: 

{
  "static_fields": {
    "client_id": "mcp-client",
    "version": "1.0"
  }
}

These fields are merged into every API request.

URL Variable Substitution

If your API URL contains variables, they're replaced from the payload:

API URL: https://api.example.com/users/{userId}/posts

Tool argument: {userId: "123"}

Result: https://api.example.com/users/123/posts

Header Variable Substitution

Headers can also use variables from the payload:

Header: Authorization: Bearer {token}

Tool argument: {token: "abc123"}

Result: Authorization: Bearer abc123

Expression Transformations

Expression transformations allow you to modify values using JavaScript:

Common Use Cases

String Concatenation: 

Expression: `"prefix-" + value + "-suffix"`
Input: `{name: "test"}`
Output: `"prefix-test-suffix"`

Number Conversion: 

Expression: `parseInt(value) * 2`
Input: `{count: "5"}`
Output: `10`

Conditional Logic: 

Expression: `value === "yes" ? true : false`
Input: `{enabled: "yes"}`
Output: `true`

Note: Expression evaluation should be used carefully. In production, consider using a sandboxed evaluator for security.

Best Practices

1. Keep Mappings Simple

Prefer direct mappings when possible. Only use expressions when necessary.

2. Document Your Mappings

Add comments or descriptions explaining why certain transformations are needed.

3. Test Your Mappings

After creating a mapping:

  1. Test with sample tool arguments
  2. Verify the API receives the correct payload
  3. Check the API response is properly formatted

4. Handle Missing Fields

Consider what happens when optional tool fields are missing:

  • Direct mappings: Field is omitted from API payload
  • Constants: Always included
  • Expressions: May cause errors if value is undefined

5. Validate Field Names

Ensure:

  • Tool field names match your tool's input schema
  • API field names match your API's expected format
  • Variable names in URLs/headers match payload field names

Common Patterns

RESTful Resource IDs

Tool: {userId: "123", action: "get"} Mapping: userId → URL variable {userId} API URL: https://api.example.com/users/{userId}

Authentication Tokens

Tool: {apiKey: "secret123"} Mapping: apiKey → Header Authorization: Bearer {apiKey}

Data Transformation

Tool: {tempC: 20} Mapping: Expression value + 273.15 → tempK Result: Converts Celsius to Kelvin

Default Values

Tool: {query: "search term"} Mapping: Constant "en" → language Result: Always includes language: "en" in payload

Troubleshooting

Mapping Not Applied

Symptoms: API receives wrong data or missing fields

Solutions:

  • Verify the mapping is saved and active
  • Check field names match exactly (case-sensitive)
  • Ensure the tool has the mapping configured
  • Verify the API is enabled

Expression Errors

Symptoms: Transformation fails with error

Solutions:

  • Check expression syntax is valid JavaScript
  • Verify the input value type matches expression expectations
  • Test the expression with sample values
  • Consider using direct mapping if expression isn't needed

Variable Substitution Not Working

Symptoms: {variableName} appears literally in URL/headers

Solutions:

  • Ensure variable name matches payload field name exactly
  • Check that the field exists in the tool arguments
  • Verify the variable is in the correct location (URL vs header vs body)

Conclusion

MCP to API mapping is a powerful system that allows you to bridge the gap between AI tool interfaces and your existing APIs. By understanding field mappings, transformations, and the complete flow, you can create robust integrations.

The key is matching tool inputs to API requirements through careful mapping configuration. Start simple with direct mappings, then add transformations as needed.

For more information, see our guides on configuring MCPs and creating APIs.