HTTP/REST Connector

The HTTP connector enables AxonFlow agents to interact with REST APIs and HTTP services with built-in security hardening, retry logic, and policy enforcement.

Overview

Property	Value
Type	http
Edition	Community
Auth Methods	Bearer, Basic, API Key, OAuth2
Capabilities	query, execute, rest-api, retry, ssrf-protection

Use Cases

• Integrate with external REST APIs
• Call internal microservices
• Fetch data from third-party services
• Webhook integrations

Security Features

The HTTP connector includes production-ready security features:

• SSRF Protection - Blocks connections to private/internal IPs by default
• Response Size Limits - Prevents memory exhaustion from large responses
• TLS 1.2+ Required - Modern encryption standards enforced
• Retry with Backoff - Handles transient failures gracefully
• Configurable Timeouts - Prevents hung connections

Configuration

Environment Variables

# Required
MCP_http_BASE_URL="https://api.example.com"

# Authentication (choose one)
# Bearer Token
MCP_http_AUTH_TYPE="bearer"
MCP_http_TOKEN="your-bearer-token"

# Basic Auth
MCP_http_AUTH_TYPE="basic"
MCP_http_USERNAME="user"
MCP_http_PASSWORD="pass"

# API Key
MCP_http_AUTH_TYPE="api-key"
MCP_http_API_KEY="your-api-key"
MCP_http_HEADER_NAME="X-API-Key"  # Default: X-API-Key

# Optional - Timeouts
MCP_http_TIMEOUT="30s"
MCP_http_READ_TIMEOUT="30s"
MCP_http_WRITE_TIMEOUT="30s"

# Optional - Retry Configuration
MCP_http_MAX_RETRIES="3"
MCP_http_RETRY_DELAY="100ms"

# Optional - Security
MCP_http_ALLOW_PRIVATE_IPS="false"  # Enable for internal APIs
MCP_http_TLS_SKIP_VERIFY="false"    # For self-signed certs (not recommended)
MCP_http_MAX_RESPONSE_SIZE="10485760"  # 10MB default

# Optional - Custom Headers
MCP_http_HEADERS='{"X-Custom-Header": "value"}'

Connector Config (Customer Portal)

{
  "name": "external-api",
  "type": "http",
  "options": {
    "base_url": "https://api.example.com",
    "auth_type": "bearer",
    "timeout": 30,
    "max_retries": 3,
    "retry_delay": "100ms",
    "headers": {
      "X-Custom-Header": "custom-value"
    }
  },
  "credentials": {
    "token": "your-bearer-token"
  }
}

Authentication Types

Bearer Token

{
  "options": {
    "auth_type": "bearer"
  },
  "credentials": {
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Adds header: Authorization: Bearer <token>

Basic Auth

{
  "options": {
    "auth_type": "basic"
  },
  "credentials": {
    "username": "user",
    "password": "pass"
  }
}

Adds header: Authorization: Basic base64(user:pass)

API Key

{
  "options": {
    "auth_type": "api-key",
    "header_name": "X-API-Key"
  },
  "credentials": {
    "api_key": "your-api-key"
  }
}

Adds header: X-API-Key: <api_key>

OAuth2

{
  "options": {
    "auth_type": "oauth2"
  },
  "credentials": {
    "access_token": "oauth-access-token"
  }
}

Adds header: Authorization: Bearer <access_token>

Operations

Query Operations (GET)

# Simple GET request
curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "external-api",
    "statement": "/users",
    "parameters": {
      "status": "active",
      "limit": 10
    }
  }'

Parameters are converted to query string: /users?status=active&limit=10

Response (Array):

{
  "success": true,
  "rows": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
  ],
  "row_count": 2,
  "duration_ms": 150
}

Response (Object):

{
  "rows": [
    {"data": {...}, "meta": {...}}
  ],
  "row_count": 1
}

Execute Operations (POST/PUT/DELETE/PATCH)

# POST - Create resource
curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "external-api",
    "action": "POST",
    "statement": "/users",
    "parameters": {
      "name": "Charlie",
      "email": "[email protected]"
    }
  }'

# PUT - Update resource
curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "external-api",
    "action": "PUT",
    "statement": "/users/123",
    "parameters": {
      "name": "Charlie Updated",
      "status": "verified"
    }
  }'

# PATCH - Partial update
curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "external-api",
    "action": "PATCH",
    "statement": "/users/123",
    "parameters": {
      "status": "inactive"
    }
  }'

# DELETE - Remove resource
curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "external-api",
    "action": "DELETE",
    "statement": "/users/123"
  }'

Response:

{
  "success": true,
  "rows_affected": 1,
  "message": "HTTP 201: {\"id\":42,\"name\":\"Charlie\"...}",
  "duration_ms": 245
}

Retry Behavior

The connector automatically retries on transient failures:

Retryable Status Codes:

• 408 Request Timeout
• 429 Too Many Requests
• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout

Retry Configuration:

Setting	Default	Description
max_retries	3	Maximum retry attempts
retry_delay	100ms	Initial delay between retries
Max backoff	5s	Maximum delay (exponential backoff)

Note: POST/PATCH requests only retry on connection errors, not HTTP errors (not idempotent).

SSRF Protection

By default, the connector blocks connections to private/internal IP ranges:

Blocked Ranges:

• 127.0.0.0/8 (loopback)
• 10.0.0.0/8 (private)
• 172.16.0.0/12 (private)
• 192.168.0.0/16 (private)
• 169.254.0.0/16 (link-local)
• ::1 (IPv6 loopback)
• fc00::/7 (IPv6 private)

To connect to internal APIs:

{
  "options": {
    "allow_private_ips": true
  }
}

Health Check

Configure a health endpoint:

{
  "options": {
    "health_path": "/health"
  }
}

curl https://your-axonflow.example.com/mcp/connectors/external-api/health

Response:

{
  "healthy": true,
  "latency_ms": 45,
  "details": {
    "base_url": "https://api.example.com",
    "status_code": "200",
    "auth_type": "bearer"
  }
}

Best Practices

Security

1. Never disable SSRF protection unless connecting to internal APIs
2. Use HTTPS for all external APIs
3. Rotate credentials regularly
4. Set appropriate timeouts to prevent hung connections
5. Limit response sizes to prevent memory exhaustion

Performance

1. Enable connection pooling (default)
2. Configure retries for unreliable APIs
3. Set appropriate timeouts based on API SLAs
4. Use compression if API supports it

Error Handling

The connector returns detailed error information:

{
  "success": false,
  "message": "HTTP 401: {\"error\":\"invalid_token\"...}",
  "duration_ms": 50
}

Rate Limiting

For APIs with rate limits, implement client-side throttling:

{
  "options": {
    "max_retries": 5,
    "retry_delay": "1s"
  }
}

Request Transformation

The HTTP connector supports request transformation to inject headers, modify the request body, or map parameters before sending requests to the upstream API.

Header Injection

Add custom headers to every request. This is useful for API versioning, client identification, or passing through upstream-specific headers:

{
  "name": "payment-api",
  "type": "http",
  "options": {
    "base_url": "https://api.payments.example.com",
    "auth_type": "bearer",
    "headers": {
      "X-API-Version": "2024-01-01",
      "X-Client-Name": "AxonFlow",
      "X-Idempotency-Key": "{{request_id}}",
      "Accept-Language": "en-US"
    }
  },
  "credentials": {
    "token": "your-bearer-token"
  }
}

Headers defined in the connector config are merged with any per-request headers. Per-request headers take precedence if there is a conflict.

Body Mapping

When the upstream API expects a different request body structure, use the statement and parameters fields to map data:

# The statement defines the path; parameters become the JSON body for POST/PUT/PATCH
curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "payment-api",
    "action": "POST",
    "statement": "/v2/charges",
    "parameters": {
      "amount": 5000,
      "currency": "usd",
      "source": "tok_visa",
      "metadata": {
        "order_id": "ord-12345",
        "customer_email": "[email protected]"
      }
    }
  }'

For GET requests, parameters are automatically mapped to query string parameters. For POST/PUT/PATCH requests, parameters are serialized as the JSON request body.

Query Parameter Mapping

For GET requests with complex query parameters:

# Parameters are URL-encoded as query string
curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -d '{
    "connector": "payment-api",
    "statement": "/v2/charges",
    "parameters": {
      "limit": 25,
      "created[gte]": 1701388800,
      "status": "succeeded"
    }
  }'

This produces the request: GET /v2/charges?limit=25&created%5Bgte%5D=1701388800&status=succeeded

Example: GitHub API Integration

{
  "name": "github-api",
  "type": "http",
  "options": {
    "base_url": "https://api.github.com",
    "auth_type": "bearer",
    "headers": {
      "Accept": "application/vnd.github.v3+json"
    },
    "timeout": 30,
    "max_retries": 3
  },
  "credentials": {
    "token": "ghp_xxxxxxxxxxxx"
  }
}

# Get repository info
curl -X POST .../query -d '{
  "connector": "github-api",
  "statement": "/repos/owner/repo"
}'

# Create issue
curl -X POST .../execute -d '{
  "connector": "github-api",
  "action": "POST",
  "statement": "/repos/owner/repo/issues",
  "parameters": {
    "title": "Bug report",
    "body": "Description...",
    "labels": ["bug"]
  }
}'

Troubleshooting

Connection Refused

• Verify base URL is correct
• Check network connectivity
• Ensure firewall allows outbound connections

SSRF Protection Error

• If connecting to internal API, set allow_private_ips: true
• Verify the target is intentionally internal

SSL Certificate Error

• Ensure server certificate is valid
• For self-signed certs (dev only): tls_skip_verify: true
• Add CA certificate to system trust store

Timeout Errors

• Increase timeout configuration
• Check API response times
• Consider implementing pagination

429 Too Many Requests

• Increase retry_delay
• Add rate limiting logic
• Contact API provider for higher limits

Related

• PostgreSQL Connector
• MongoDB Connector
• MCP Overview