Skip to content

MCP API Service Example

Jump to bottom
Mo Abualruz edited this page Dec 6, 2025 · 1 revision

MCP API Service Example

Status: ✅ Complete

Last Updated: December 6, 2025

Overview

This example demonstrates integrating an API service MCP server with RiceCoder. The API server provides tools for making HTTP requests to external APIs.

Setup

1. Install API MCP Server

# Install via npm
npm install -g api-mcp-server

# Or use Node.js directly
node ./api-server.js

2. Configure MCP Server

Create .ricecoder/mcp-servers.yaml:

servers:
  - id: api-server
    name: API Tools
    command: node
    args:
      - ./api-server.js
      - --port
      - "3000"
    env:
      API_KEY: ${API_KEY}
      API_URL: https://api.example.com
      API_TIMEOUT: "10000"
      LOG_LEVEL: INFO
    timeout_ms: 10000
    auto_reconnect: true
    max_retries: 5

3. Set Environment Variables

export API_KEY=your_api_key

4. Verify Connection

ricecoder tools list

Expected output:

Available Tools:

api-get (api-server)
  Description: Make GET request to API
  Category: api
  Parameters: endpoint (string, required), headers (object, optional)
  Returns: object

api-post (api-server)
  Description: Make POST request to API
  Category: api
  Parameters: endpoint (string, required), data (object, required), headers (object, optional)
  Returns: object

api-put (api-server)
  Description: Make PUT request to API
  Category: api
  Parameters: endpoint (string, required), data (object, required), headers (object, optional)
  Returns: object

api-delete (api-server)
  Description: Make DELETE request to API
  Category: api
  Parameters: endpoint (string, required), headers (object, optional)
  Returns: object

Configure Permissions

Create .ricecoder/permissions.yaml:

permissions:
  # Allow all GET requests (read-only)
  - pattern: "api-get"
    level: allow
  
  # Ask for POST requests (create)
  - pattern: "api-post"
    level: ask
  
  # Ask for PUT requests (update)
  - pattern: "api-put"
    level: ask
  
  # Ask for DELETE requests (delete)
  - pattern: "api-delete"
    level: ask

Usage Examples

Example 1: GET Request

ricecoder tools invoke api-get \
  --endpoint "/users/123"

Output:

{
  "success": true,
  "status": 200,
  "data": {
    "id": 123,
    "name": "Alice",
    "email": "alice@example.com",
    "created_at": "2025-01-01T00:00:00Z"
  }
}

Example 2: POST Request

ricecoder tools invoke api-post \
  --endpoint "/users" \
  --data '{"name": "Bob", "email": "bob@example.com"}'

Output:

{
  "success": true,
  "status": 201,
  "data": {
    "id": 124,
    "name": "Bob",
    "email": "bob@example.com",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Example 3: PUT Request

ricecoder tools invoke api-put \
  --endpoint "/users/123" \
  --data '{"name": "Alice Updated", "email": "alice.updated@example.com"}'

Output:

{
  "success": true,
  "status": 200,
  "data": {
    "id": 123,
    "name": "Alice Updated",
    "email": "alice.updated@example.com",
    "updated_at": "2025-01-15T11:00:00Z"
  }
}

Example 4: DELETE Request

ricecoder tools invoke api-delete \
  --endpoint "/users/124"

Output:

{
  "success": true,
  "status": 204,
  "message": "User deleted successfully"
}

Example 5: GET with Custom Headers

ricecoder tools invoke api-get \
  --endpoint "/users" \
  --headers '{"Accept": "application/json", "X-Custom-Header": "value"}'

Output:

{
  "success": true,
  "status": 200,
  "data": [
    {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    },
    {
      "id": 124,
      "name": "Bob",
      "email": "bob@example.com"
    }
  ]
}

Integration with Agents

Code Generator Agent

The code generator can use API tools to:

  • Fetch API specifications
  • Generate code from API responses
  • Create API client code
// Fetch API specification
let spec = agent.invoke_tool("api-get",
  json!({"endpoint": "/api/spec"})
).await?;

// Generate code from spec
let generated_code = generate_client_code(&spec);

// Return generated code
Ok(generated_code)

Data Sync Agent

The data sync agent can use API tools to:

  • Fetch data from external APIs
  • Transform and store data
  • Keep data in sync
// Fetch data from API
let users = agent.invoke_tool("api-get",
  json!({"endpoint": "/users"})
).await?;

// Transform data
let transformed = transform_users(&users);

// Store in local database
store_users(&transformed).await?;

Integration Agent

The integration agent can use API tools to:

  • Integrate with third-party services
  • Sync data between systems
  • Trigger external workflows
// Fetch data from source API
let data = agent.invoke_tool("api-get",
  json!({"endpoint": "/source/data"})
).await?;

// Send to destination API
agent.invoke_tool("api-post",
  json!({
    "endpoint": "/destination/data",
    "data": data
  })
).await?;

Configuration Files

.ricecoder/mcp-servers.yaml

servers:
  - id: api-server
    name: API Tools
    command: node
    args:
      - ./api-server.js
      - --port
      - "3000"
    env:
      API_KEY: ${API_KEY}
      API_URL: https://api.example.com
      API_TIMEOUT: "10000"
      LOG_LEVEL: INFO
    timeout_ms: 10000
    auto_reconnect: true
    max_retries: 5

.ricecoder/permissions.yaml

permissions:
  # Allow all GET requests (read-only)
  - pattern: "api-get"
    level: allow
  
  # Ask for POST requests (create)
  - pattern: "api-post"
    level: ask
  
  # Ask for PUT requests (update)
  - pattern: "api-put"
    level: ask
  
  # Ask for DELETE requests (delete)
  - pattern: "api-delete"
    level: ask
  
  # Per-agent: Allow data sync agent to write
  - pattern: "api-post"
    level: allow
    agent_id: data-sync
  
  - pattern: "api-put"
    level: allow
    agent_id: data-sync

Error Handling

API Error Response

Error: API request failed with status 404

Output:

{
  "success": false,
  "status": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Solutions:

  1. Check endpoint is correct
  2. Verify resource exists
  3. Check API documentation

Authentication Error

Error: API request failed with status 401

Output:

{
  "success": false,
  "status": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Solutions:

  1. Check API key is set: export API_KEY=...
  2. Verify API key is valid
  3. Check API key has required permissions

Timeout Error

Error: Tool 'api-get' timed out after 10000ms

Solutions:

  1. Increase timeout: timeout_ms: 15000
  2. Check API server performance
  3. Check network connectivity
  4. Optimize API request

Troubleshooting

Server Won't Start

Error: Failed to start API server

Solutions:

  1. Check Node.js is installed: node --version
  2. Check API server script exists: ls ./api-server.js
  3. Check port is available: lsof -i :3000
  4. Check environment variables are set

Connection Refused

Error: Failed to connect to API server

Solutions:

  1. Check API server is running: ps aux | grep api-server
  2. Check port is correct: --port 3000
  3. Check network connectivity
  4. Restart API server

Permission Denied

Error: Permission denied for tool 'api-post'

Solutions:

  1. Check permissions in .ricecoder/permissions.yaml
  2. Verify permission level is not "deny"
  3. Check per-agent permissions
  4. Update permissions if needed

See Also

Last updated: December 6, 2025

Clone this wiki locally