# 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

```bash
# 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`:

```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

```bash
export API_KEY=your_api_key
```

### 4. Verify Connection

```bash
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`:

```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

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

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

### Example 2: POST Request

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

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

### Example 3: PUT Request

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

Output:
```json
{
  "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

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

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

### Example 5: GET with Custom Headers

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

Output:
```json
{
  "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

```rust
// 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

```rust
// 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

```rust
// 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

```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

```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**:
```json
{
  "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**:
```json
{
  "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

- [MCP Integration](./MCP-Integration.md)
- [MCP Server Configuration](./MCP-Server-Configuration.md)
- [Permission Configuration](./MCP-Permissions.md)
- [MCP Database Server Example](./MCP-Database-Server-Example.md)

---

*Last updated: December 6, 2025*