How to Create MCP Tools

MCP tools are the interface that AI assistants use to interact with your APIs. This guide will show you how to create and configure tools in the admin panel.

What are MCP Tools?

MCP tools are functions that AI assistants can call. Each tool:

Has a name and description that AI assistants understand
Defines input parameters through a JSON Schema
Maps to an API endpoint that performs the actual work
Can be discovered and invoked by MCP-compatible clients

Creating Your First Tool

Step 1: Navigate to MCP Detail Page

Log in to the admin panel
Navigate to the MCPs section
Click on an MCP to view its detail page
Find the Tools section

Step 2: Click "Create Tool"

In the Tools section, click the Create Tool button to open the tool creation form.

Step 3: Configure Tool Details

Name

The tool name is how AI assistants will identify and call your tool. Choose a clear, descriptive name:

Good: get_weather, create_customer, search_products
Avoid: tool1, api_call, function

Naming conventions:

Use lowercase with underscores: get_user_profile
Be descriptive: get_weather_by_city not weather
Use action verbs: create, get, update, delete, search

Description

Write a clear description of what the tool does. This helps AI assistants understand when to use it:

Example:

Retrieves current weather information for a specified city. Returns temperature, conditions, humidity, and wind speed.

Tips for descriptions:

Explain what the tool does, not how it works
Mention key parameters
Describe the expected output
Use natural language that AI assistants can understand

Input Schema (JSON Schema)

The input schema defines what parameters the tool accepts. This is a JSON Schema that describes the structure and validation rules.

Basic Example:

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "The name of the city"
    },
    "unit": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"],
      "description": "Temperature unit"
    }
  },
  "required": ["city"]
}

Simplified Format Support:

The admin panel supports a simplified format for easier tool creation:

Type-based:

{
  "city": "string",
  "temperature": "number",
  "enabled": "boolean"
}

Description-based:

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

The system automatically converts simplified formats to full JSON Schema.

Common Schema Patterns:

String with validation:

{
  "email": {
    "type": "string",
    "format": "email",
    "description": "User email address"
  }
}

Number with range:

{
  "age": {
    "type": "number",
    "minimum": 0,
    "maximum": 150,
    "description": "Person's age"
  }
}

Enum (choice of values):

{
  "status": {
    "type": "string",
    "enum": ["active", "inactive", "pending"],
    "description": "Account status"
  }
}

Array:

{
  "tags": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "description": "List of tags"
  }
}

Nested objects:

{
  "address": {
    "type": "object",
    "properties": {
      "street": {"type": "string"},
      "city": {"type": "string"},
      "zip": {"type": "string"}
    },
    "required": ["street", "city"]
  }
}

URI (Optional)

The URI is an optional identifier for the tool. It's used for resource identification in some MCP contexts.

Examples:

weather://current
api://users/create
mcp://weather/forecast

If not specified, the system will generate one based on the tool name.

Step 4: Save the Tool

Click Create Tool to save. The tool will appear in the Tools section of your MCP.

Complete Example

Here's a complete example of creating a weather tool:

Name: get_weather

Description: Retrieves current weather conditions for a specified city. Returns temperature, humidity, wind speed, and conditions.

Input Schema:

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "The name of the city"
    },
    "country": {
      "type": "string",
      "description": "Country code (e.g., 'US', 'GB')"
    },
    "unit": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"],
      "default": "celsius",
      "description": "Temperature unit"
    }
  },
  "required": ["city"]
}

URI: weather://current

Best Practices

1. Clear Naming

Use descriptive, action-oriented names
Follow consistent naming conventions
Avoid abbreviations unless widely understood

2. Comprehensive Descriptions

Explain what the tool does
Mention important parameters
Describe expected behavior
Include any limitations or requirements

3. Well-Defined Schemas

Use appropriate data types
Add descriptions to all fields
Mark required fields
Use enums for limited choices
Add validation where appropriate

4. Required vs Optional Fields

Only mark fields as required if they're truly necessary:

Required: Essential parameters (e.g., city for weather)
Optional: Nice-to-have parameters (e.g., unit with a default)

5. Schema Validation

Add validation to help AI assistants provide correct inputs:

String formats: email, date, uri
Number ranges: minimum, maximum
String patterns: pattern with regex
Array constraints: minItems, maxItems

Common Patterns

Search Tools

{
  "query": {
    "type": "string",
    "description": "Search query"
  },
  "limit": {
    "type": "number",
    "minimum": 1,
    "maximum": 100,
    "default": 10,
    "description": "Maximum number of results"
  }
}

Creation Tools

{
  "name": {
    "type": "string",
    "description": "Resource name"
  },
  "data": {
    "type": "object",
    "description": "Additional resource data"
  }
}

Update Tools

{
  "id": {
    "type": "string",
    "description": "Resource identifier"
  },
  "updates": {
    "type": "object",
    "description": "Fields to update"
  }
}

Next Steps

After creating your tool:

Map Tool to API: Connect the tool to an API endpoint
Test the Tool: Verify it works with sample inputs
Refine the Schema: Adjust based on actual usage

Troubleshooting

Tool not appearing?

Check that the MCP is enabled
Verify the tool was saved successfully
Refresh the page

Schema validation errors?

Ensure valid JSON syntax
Check that types are correct
Verify required fields are properly marked

AI assistant not using tool?

Improve the description to be more specific
Check that the tool name is clear
Ensure the schema matches expected inputs

Conclusion

Creating MCP tools is about defining clear interfaces that AI assistants can understand and use. Focus on descriptive names, comprehensive descriptions, and well-structured input schemas.

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