← Back to MCP Agent

MCP Agent Quick Start

Get AI-powered API access running in 5 minutes.

Prerequisites

  • MicroRapid CLI installed (Installation Guide →)
  • An API with OpenAPI/Swagger specification
  • AI assistant with MCP support (Claude Desktop, etc.)

Step 1: Initialize MCP Agent

# Initialize from an OpenAPI spec
mrapids-agent init my-api --from-url https://api.example.com/openapi.yaml

# Or from a local file
mrapids-agent init my-api --from-file ./api-spec.yaml

# Or use a built-in example
mrapids-agent init stripe --example stripe

This creates:

📁 .mrapids/
  ├── 📄 config.yaml      # Agent configuration
  ├── 📄 policy.yaml      # Security policies
  └── 📄 credentials.yaml # Credential references

Step 2: Add Authentication

# Add API key from environment variable
mrapids-agent auth add --name my-api --env MY_API_KEY

# Set the environment variable
export MY_API_KEY="your-actual-api-key"

# For bearer token authentication
mrapids-agent auth add --name my-api --bearer --env MY_BEARER_TOKEN

Step 3: Configure Security Policy

Edit .mrapids/policy.yaml:

# Start with read-only access
policies:
  - name: "default"
    description: "Read-only access for AI"
    rules:
      - allow:
          methods: ["GET", "HEAD", "OPTIONS"]
      - deny:
          methods: ["POST", "PUT", "DELETE", "PATCH"]
    
    # Optional: Restrict to specific paths
    paths:
      allow:
        - "/api/v1/users/*"
        - "/api/v1/products/*"
      deny:
        - "/api/v1/admin/*"
    
    # Optional: Rate limiting (configuration only)
    # Enforcement coming in future update
    limits:
      requests_per_minute: 30
      requests_per_hour: 500

Step 4: Start MCP Agent

# Start the agent
mrapids-agent start

🚀 MCP Agent started successfully!
📍 Listening on: stdio
🔒 Policy: default (read-only)
✅ Ready for AI connections

Step 5: Connect Your AI Assistant

For Claude Desktop

  1. Open Claude Desktop settings
  2. Go to Developer → MCP Servers
  3. Add configuration:
{
  "mcpServers": {
    "my-api": {
      "command": "mrapids-agent",
      "args": ["start"],
      "cwd": "/path/to/your/project"
    }
  }
}
  1. Restart Claude Desktop

For Other MCP-Compatible Tools

# Get connection details
mrapids-agent info

# Output:
# MCP Server: mrapids-agent
# Protocol: stdio
# Working Directory: /path/to/project

Step 6: Test the Connection

In your AI assistant, try:

“Can you list the available API operations?”

The AI should respond with available endpoints. Then try:

“Get the user with ID 123”

You should see the API request executed with full security controls.

Common Patterns

Development vs Production

# .mrapids/config.yaml
environments:
  development:
    base_url: "https://api-dev.example.com"
    policy: "dev-write-access"
  
  production:
    base_url: "https://api.example.com"
    policy: "prod-readonly"

# Switch environments
mrapids-agent start --env production

Allowing Specific Write Operations

policies:
  - name: "customer-support"
    rules:
      # Read everything
      - allow:
          methods: ["GET"]
      
      # Only update customer records
      - allow:
          methods: ["PUT", "PATCH"]
          paths: ["/api/v1/customers/*"]
      
      # Never delete
      - deny:
          methods: ["DELETE"]

Environment-Specific Policies

environments:
  development:
    base_url: "https://api-dev.example.com"
    policy: "dev-write-access"
  
  production:
    base_url: "https://api.example.com"
    policy: "prod-readonly"

# Switch environments
mrapids-agent start --env production

Sensitive Data Redaction

# .mrapids/config.yaml
redaction:
  enabled: true
  patterns:
    # Built-in patterns
    - ssn
    - credit_card
    - api_key
    
    # Custom patterns
    - name: "employee_id"
      pattern: "EMP[0-9]{6}"
      replacement: "[EMPLOYEE_ID]"

Monitoring & Debugging

View Logs

# Follow logs in real-time
mrapids-agent logs -f

# Filter by severity
mrapids-agent logs --level error

# Export for analysis
mrapids-agent logs --export audit.json

Test Policies

# Test a specific request
mrapids-agent policy test --method GET --path /api/v1/users

# Validate policy syntax
mrapids-agent policy validate

Monitor Usage

# Show current session stats
mrapids-agent stats

# Output:
# Session: 2h 15m
# Requests: 145
# Allowed: 142
# Blocked: 3
# Errors: 0

Troubleshooting

AI Can’t See MCP Agent

  1. Check agent is running: mrapids-agent status
  2. Verify AI configuration points to correct directory
  3. Restart AI application after config changes

Permission Denied Errors

  1. Check policy allows the operation: mrapids-agent policy test
  2. Review logs for specific denial reason
  3. Update policy if needed and restart

Authentication Failures

  1. Verify credentials: mrapids-agent auth test
  2. Check environment variables are set
  3. Ensure API keys haven’t expired

Security Best Practices

  1. Start with minimal permissions - Begin read-only, add access as needed
  2. Use environment-specific policies - Different rules for dev/prod
  3. Enable audit logging - Track all AI actions
  4. Set rate limits - Prevent runaway requests
  5. Review logs regularly - Monitor for unusual patterns

Next Steps