Skip to main content

​
Generate Your First MCP Tool in 30 Seconds

This guide will walk you through using Tools to transform any API into an AI-ready MCP tool in seconds.

​
Step 1: Install Tools

# Instant execution with uvx (recommended)
uvx automagik-tools --version

# Or install with pip
pip install automagik-tools

# Verify installation
automagik-tools --version

​
Step 2: Generate from OpenAPI Spec

Let’s create an MCP tool from the PetStore API: 
# Generate tool from OpenAPI spec
automagik-tools generate \
  --spec https://petstore3.swagger.io/api/v3/openapi.json \
  --name petstore \
  --output ./tools

# Output:
# ✓ OpenAPI spec fetched
# ✓ Parsing endpoints (20 found)
# ✓ Generating types
# ✓ Creating tool implementations
# ✓ Writing tests
# ✓ Tool generated: ./tools/petstore

# Generated in 8.2 seconds!

​
Step 3: Serve Your Tool

# Start MCP server with your new tool
automagik-tools serve --tools petstore

# Or with uvx (no install needed)
uvx automagik-tools serve --tools petstore

# Server starts:
# 🛠️  Tools v1.0.0
# ✓ Tool loaded: petstore (20 operations)
# ✓ MCP server listening on port 3000

​
Step 4: Use in Claude Desktop

Add to claude_desktop_config.json: 
{
  "mcpServers": {
    "petstore": {
      "command": "uvx",
      "args": ["automagik-tools", "serve", "--tools", "petstore"]
    }
  }
}
Restart Claude Desktop. Now you can: 
You: "Use the petstore tool to find available pets"

Claude: I'll search for available pets.
[Uses petstore_find_pets tool with status="available"]

Found 5 available pets:
- Doggo (ID: 1) - Golden Retriever
- Mittens (ID: 2) - Cat
- Nemo (ID: 3) - Fish
...

​
Real-World Example: GitHub API Integration

Generate a GitHub tool in 30 seconds:
1

Generate GitHub Tool

automagik-tools generate \
  --spec https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json \
  --name github \
  --output ./tools

# Generates tool with 600+ operations!
2

Configure Authentication

# Set GitHub token
export GITHUB_TOKEN=ghp_your_token_here

# Or in .env
echo "GITHUB_TOKEN=ghp_your_token" >> .env
3

Serve GitHub Tool

automagik-tools serve --tools github

# Now AI agents can:
# - Create issues
# - List PRs
# - Create repositories
# - Manage webhooks
# - And 600+ more operations!

​
Using Pre-Built Integrations

Tools comes with 9 native integrations ready to use: 
# List available integrations
automagik-tools integrations list

# Available integrations:
# - github: GitHub API (650 operations)
# - slack: Slack API (140 operations)
# - stripe: Stripe API (380 operations)
# - discord: Discord API (210 operations)
# - linear: Linear API (120 operations)
# - notion: Notion API (80 operations)
# - sendgrid: SendGrid API (45 operations)
# - twilio: Twilio API (90 operations)
# - airtable: Airtable API (35 operations)
Enable an integration: 
# Enable GitHub integration
automagik-tools integrations enable github \
  --token ghp_your_token

# Enable Slack integration
automagik-tools integrations enable slack \
  --token xoxb-your-slack-token

# Serve multiple integrations
automagik-tools serve --tools github,slack,stripe

​
Custom API Example

Generate a tool for your own API:
  • From URL
  • From Local File
  • From Postman Collection
# Your API has OpenAPI docs at /openapi.json
automagik-tools generate \
  --spec https://api.mycompany.com/openapi.json \
  --name mycompany-api \
  --output ./tools

​
Serve Multiple Tools

Create a tool registry for your organization: 
# Generate multiple tools
automagik-tools generate --spec https://api1.com/spec.json --name api1
automagik-tools generate --spec https://api2.com/spec.json --name api2
automagik-tools generate --spec https://api3.com/spec.json --name api3

# Serve all tools together
automagik-tools serve --tools api1,api2,api3

# Or serve everything in tools/
automagik-tools serve --tools-dir ./tools

# MCP server now exposes all tools!

​
Tool Discovery

Let AI agents discover available tools: 
# Enable tool discovery
automagik-tools serve --discovery

# Agents can query:
# - List all available tools
# - Search tools by capability
# - Get tool documentation
# - View usage examples
Example from Claude: 
You: "What tools are available?"

Claude: Let me check available tools.
[Uses list_available_tools]

Available tools:
- github: GitHub API integration (650 operations)
- slack: Slack messaging (140 operations)
- stripe: Payment processing (380 operations)

You: "Find tools that can send messages"

Claude: [Uses search_tools with query="send messages"]

Found 2 tools:
- slack: Send messages to channels/users
- twilio: Send SMS messages

​
Common Patterns

  • Internal API Catalog
  • Customer Support Bot
  • E-commerce Integration
# Create tools for all internal APIs
automagik-tools generate \
  --spec https://api.users.internal/spec.json \
  --name users-api

automagik-tools generate \
  --spec https://api.products.internal/spec.json \
  --name products-api

automagik-tools generate \
  --spec https://api.orders.internal/spec.json \
  --name orders-api

# Serve as internal tool registry
automagik-tools serve \
  --tools users-api,products-api,orders-api \
  --port 3000 \
  --discovery

​
Validation & Testing

Ensure generated tools work correctly: 
# Validate OpenAPI spec before generating
automagik-tools validate-spec \
  --spec https://api.example.com/openapi.json

# Generate with tests
automagik-tools generate \
  --spec https://api.example.com/openapi.json \
  --name my-api \
  --include-tests

# Run tests
cd tools/my-api
pytest

# Test tool via MCP
automagik-tools test --tool my-api --operation list_users

​
Pro Tips

# No installation needed!
# Perfect for CI/CD or distributed teams

uvx automagik-tools serve --tools github,slack

# Or in CI/CD:
uvx automagik-tools generate \
  --spec $API_SPEC_URL \
  --name generated-tool \
  --output ./dist

# Store OpenAPI specs in repo
mkdir specs/
curl https://api.example.com/openapi.json > specs/api.json

# Generate from local spec
automagik-tools generate --spec specs/api.json --name api

# Regenerate when spec changes
git pull
automagik-tools generate --spec specs/api.json --name api --force

# Separate tool collections
automagik-tools serve \
  --tools github,linear \
  --port 3001 \
  --name dev-tools

automagik-tools serve \
  --tools slack,sendgrid \
  --port 3002 \
  --name communication-tools

automagik-tools serve \
  --tools stripe,airtable \
  --port 3003 \
  --name business-tools

​
Next Steps

Custom Tools

Learn to:
  • Extend generated tools
  • Add custom logic
  • Override operations

Tool Registry

Build:
  • Centralized tool catalog
  • Version management
  • Usage tracking

Advanced MCP

Explore:
  • Tool composition
  • Context sharing
  • Agent coordination

Production Deployment

Deploy:
  • As a service
  • Load balancing
  • Monitoring

​
Troubleshooting

Validate your spec first:
# Use OpenAPI validator
automagik-tools validate-spec --spec your-spec.yaml

# Common issues:
# - Invalid YAML/JSON syntax
# - Missing required fields
# - Unsupported OpenAPI version

# Try converting to OpenAPI 3.0
automagik-tools convert-spec \
  --spec swagger-2.0-spec.json \
  --output openapi-3.0-spec.json
Check dependencies and test:
# Generate with verbose output
automagik-tools generate \
  --spec spec.json \
  --name my-tool \
  --verbose

# Test generated tool
automagik-tools test --tool my-tool

# Check tool structure
cd tools/my-tool
ls -la
Configure auth properly:
# For token auth
export API_TOKEN=your-token

# For OAuth
export OAUTH_CLIENT_ID=your-client-id
export OAUTH_CLIENT_SECRET=your-secret

# Test authentication
automagik-tools integrations test my-tool
Congratulations! 🎉 You’ve generated your first MCP tool with Tools. You can now connect any API to any AI agent in seconds!

Join the Community

Share your generated tools and API integrations