MCP REST Server

A Model Context Protocol (MCP) server that provides REST API client functionality with authentication support and Swagger documentation integration.

Features

• Multiple Authentication Methods: Support for both token-based and login-based authentication
• Swagger Integration: Automatic endpoint discovery and documentation from OpenAPI/Swagger specs
• Automatic Token Management: Handles token refresh and re-authentication
• Comprehensive HTTP Methods: Support for GET, POST, PUT, DELETE, and PATCH requests
• Error Handling: Robust error handling with retry logic
• MCP Compatible: Fully compatible with the Model Context Protocol

Development

npm run dev

Available Tools

1. configure_rest_client

Configure the REST client with authentication and API details.

Parameters:

• baseUrl (required): Base URL for the REST API
• auth (required): Authentication configuration (token or login)
• swaggerUrl (optional): URL to Swagger/OpenAPI documentation
• timeout (optional): Request timeout in milliseconds (default: 30000)
• retries (optional): Number of retries for failed requests (default: 3)

2. http_request

Make HTTP requests to the configured API.

Parameters:

• method (required): HTTP method (GET, POST, PUT, DELETE, PATCH)
• path (required): API endpoint path
• params (optional): Query parameters or request body parameters
• body (optional): Request body for POST, PUT, PATCH requests
• headers (optional): Additional headers

3. get_swagger_documentation

Get the complete list of available endpoints from Swagger documentation.

4. search_endpoints

Search for endpoints in the Swagger documentation.

Parameters:

• query (required): Search query to find matching endpoints

5. get_endpoint_info

Get detailed information about a specific endpoint.

Parameters:

• path (required): Endpoint path
• method (required): HTTP method

6. check_authentication

Check if the client is currently authenticated.

7. logout

Logout and clear authentication state.

Authentication Flow

Token Authentication

1. Token is stored and used immediately
2. Added to requests as Authorization: Bearer <token>
3. If 401 received, no automatic retry (token assumed invalid)

Login Authentication

1. Makes login request to specified endpoint
2. Extracts token from response using tokenField
3. Stores token in memory
4. Adds token to subsequent requests
5. If 401 received, automatically re-authenticates and retries

Error Handling

• Network errors: Automatic retry with exponential backoff
• Authentication errors: Automatic re-authentication for login-based auth
• Validation errors: Clear error messages with details
• API errors: HTTP status and error message forwarding

Development

Project Structure

src/
├── types.ts          # TypeScript type definitions
├── auth.ts           # Authentication manager
├── swagger.ts        # Swagger documentation parser
├── rest-client.ts    # REST client implementation
└── index.ts          # MCP server implementation

Building

npm run build

Running

npm start

Installation

npm install
npm run build

Configuration

The server supports two authentication methods:

Token Authentication

{
  "baseUrl": "https://api.example.com",
  "swaggerUrl": "https://api.example.com/swagger.json",
  "auth": {
    "type": "token",
    "token": "your-api-token-here"
  },
  "timeout": 30000,
  "retries": 3
}

Login Authentication

{
  "baseUrl": "https://api.example.com",
  "swaggerUrl": "https://api.example.com/swagger.json",
  "auth": {
    "type": "login",
    "username": "your-username",
    "password": "your-password",
    "loginEndpoint": "/auth/login",
    "tokenField": "access_token"
  },
  "timeout": 30000,
  "retries": 3
}

Usage Examples

Basic Setup

1. Configure the client:

{
  "baseUrl": "https://jsonplaceholder.typicode.com",
  "auth": {
    "type": "token",
    "token": "dummy-token"
  }
}

2. Make a GET request:

{
  "method": "GET",
  "path": "/posts/1"
}

3. Make a POST request:

{
  "method": "POST",
  "path": "/posts",
  "body": {
    "title": "New Post",
    "body": "Post content",
    "userId": 1
  }
}

With Swagger Documentation

{
  "baseUrl": "https://petstore.swagger.io/v2",
  "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json",
  "auth": {
    "type": "token",
    "token": "your-api-key"
  }
}

Then you can:

• Search endpoints: search_endpoints with query "pet"
• Get endpoint info: get_endpoint_info with path "/pet" and method "POST"
• View all documentation: get_swagger_documentation

MCP Client Configuration

The MCP REST server now supports automatic configuration through multiple methods, eliminating the need to configure APIs manually for each project.

Configuration Methods (in order of priority)

1. Command Line Arguments (highest priority)
2. Environment Variables
3. Configuration File
4. Manual Configuration (via MCP tools - lowest priority)

Cursor Configuration

Option 1: Auto-Configuration with Environment Variables (Recommended)

{
  "mcpServers": {
    "mcp-rest-github": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js"],
      "env": {
        "MCP_REST_BASE_URL": "https://api.github.com",
        "MCP_REST_AUTH_TYPE": "token",
        "MCP_REST_TOKEN": "your-github-token-here",
        "MCP_REST_SWAGGER_URL": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"
      }
    },
    "mcp-rest-petstore": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js"],
      "env": {
        "MCP_REST_BASE_URL": "https://petstore.swagger.io/v2",
        "MCP_REST_AUTH_TYPE": "token",
        "MCP_REST_TOKEN": "your-api-key",
        "MCP_REST_SWAGGER_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

Option 2: Auto-Configuration with Config Files

{
  "mcpServers": {
    "mcp-rest-github": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js", "--config", "/path/to/your/mcp-rest/examples/github-api.json"]
    },
    "mcp-rest-petstore": {
      "command": "node",
      "args": ["/path/to/your/mcp-rest/dist/index.js", "--config", "/path/to/your/mcp-rest/examples/petstore.json"]
    }
  }
}

Option 3: Auto-Configuration with Command Line Arguments

{
  "mcpServers": {
    "mcp-rest-github": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-rest/dist/index.js",
        "--base-url", "https://api.github.com",
        "--auth-type", "token",
        "--token", "your-github-token-here",
        "--swagger-url", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"
      ]
    }
  }
}

Claude Desktop Configuration

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Use the same configuration options as Cursor above.

Configuration Examples

The project includes several example configurations in the examples/ directory:

• examples/github-api.json - GitHub API configuration
• examples/petstore.json - Swagger Petstore API configuration
• examples/jsonplaceholder.json - JSONPlaceholder API configuration

Environment Variables

Note: Replace /path/to/your/mcp-rest/ with the actual path to your MCP REST server directory.

Usage in Claude/Cursor

With Auto-Configuration (Recommended)

If you've configured the server with auto-configuration (environment variables, CLI args, or config file), the server will be ready to use immediately:

Make a GET request to /posts/1
Show me all available endpoints
Search for endpoints related to "user"

With Manual Configuration

If you haven't provided auto-configuration, you can still configure the client manually:

1. Configure the client first:

Please configure the REST client with:
- Base URL: https://api.example.com
- Authentication: token
- Token: your-api-token-here
- Swagger URL: https://api.example.com/swagger.json

2. Then make API requests:

Make a GET request to /users/123

Testing the Configuration

You can test your configuration before using it in Claude/Cursor:

# Test with config file
node dist/index.js --config examples/jsonplaceholder.json

# Test with CLI arguments
node dist/index.js --base-url https://api.github.com --auth-type token --token your-token

# Test with environment variables
MCP_REST_BASE_URL=https://httpbin.org MCP_REST_AUTH_TYPE=token MCP_REST_TOKEN=test node dist/index.js

If you see "✅ Auto-configured REST client for [URL]", the configuration is working correctly.

License

MIT