API Client MCP Server

An enterprise-grade Model Context Protocol (MCP) server that functions like Postman for making HTTP API requests. It supports multiple authentication methods including OAuth 2.0 workflows.

Features

• HTTP Requests: Full support for GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
• Authentication Methods:
  • Bearer Token
  • Basic Authentication
  • API Key (header or query)
  • OAuth 2.0 (Password Grant, Client Credentials, Authorization Code with PKCE)
• Request History: Track and review previous requests
• Security: Enterprise-grade security practices with credential redaction
• Base URL Support: Configure a base URL for all requests
• Default Headers: Set headers that apply to all requests

📦 Installation

Install from npm

npm install -g @dilina0914/api-client-mcp

Or use directly with npx (no installation required):

npx @dilina0914/api-client-mcp

🔧 IDE Integration

Cursor IDE

Option 1: Using npx (Recommended - No Installation)

Create or edit the file .cursor/mcp.json in your project root or global Cursor settings:

{
  "mcpServers": {
    "api-client": {
      "command": "npx",
      "args": ["-y", "@dilina0914/[email protected]"]
    }
  }
}

Option 2: Using Global Installation

First, install globally:

npm install -g @dilina0914/api-client-mcp

Then configure .cursor/mcp.json:

{
  "mcpServers": {
    "api-client": {
      "command": "api-client-mcp"
    }
  }
}

Option 3: Using Local Installation

Install in your project:

npm install @dilina0914/api-client-mcp

Then configure .cursor/mcp.json:

{
  "mcpServers": {
    "api-client": {
      "command": "node",
      "args": ["node_modules/@dilina0914/api-client-mcp/dist/index.js"]
    }
  }
}

Cursor Configuration Location

• Project-specific: Create .cursor/mcp.json in your project root
• Global (all projects):
  • Windows: %APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp.json
  • macOS: ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json
  • Linux: ~/.config/Cursor/User/globalStorage/cursor.mcp/mcp.json

After configuration, restart Cursor to load the MCP server.

Visual Studio Code

VS Code requires the MCP Extension or a compatible extension that supports MCP servers.

Option 1: Using npx (Recommended)

Add to your VS Code settings (settings.json):

{
  "mcp.servers": {
    "api-client": {
      "command": "npx",
      "args": ["-y", "@dilina0914/api-client-mcp"]
    }
  }
}

Option 2: Using Global Installation

First, install globally:

npm install -g @dilina0914/api-client-mcp

Then add to settings.json:

{
  "mcp.servers": {
    "api-client": {
      "command": "api-client-mcp"
    }
  }
}

Option 3: Using Project Installation

Install in your project:

npm install @dilina0914/api-client-mcp

Then add to .vscode/settings.json in your project:

{
  "mcp.servers": {
    "api-client": {
      "command": "node",
      "args": ["${workspaceFolder}/node_modules/@dilina0914/api-client-mcp/dist/index.js"]
    }
  }
}

VS Code Settings Location

• User settings: Press Ctrl+, (Windows/Linux) or Cmd+, (macOS), then click "Open Settings (JSON)"
• Workspace settings: Create .vscode/settings.json in your project root

Verify Installation

After configuring your IDE, you can verify the MCP server is working by asking your AI assistant:

"What API client tools are available?"

The assistant should list the available tools like make_request, set_auth, etc.

🛠️ Available Tools

make_request

Makes an HTTP request to an API endpoint.

{
  "method": "GET",
  "url": "https://api.example.com/users",
  "headers": {
    "Accept": "application/json"
  },
  "queryParams": {
    "page": "1",
    "limit": "10"
  }
}

{
  "method": "POST",
  "url": "https://api.example.com/users",
  "body": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

set_auth

Configures authentication for subsequent requests.

Bearer Token

{
  "type": "bearer",
  "token": "your-access-token"
}

Basic Authentication

{
  "type": "basic",
  "username": "[email protected]",
  "password": "your-password"
}

API Key

{
  "type": "api_key",
  "key": "X-API-Key",
  "value": "your-api-key",
  "location": "header"
}

OAuth 2.0 - Password Grant

{
  "type": "oauth2",
  "grantType": "password",
  "tokenUrl": "https://auth.example.com/oauth/token",
  "username": "[email protected]",
  "password": "your-password",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "scope": "read write"
}

OAuth 2.0 - Client Credentials

{
  "type": "oauth2",
  "grantType": "client_credentials",
  "tokenUrl": "https://auth.example.com/oauth/token",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "scope": "api.read api.write"
}

OAuth 2.0 - Authorization Code (with PKCE)

{
  "type": "oauth2",
  "grantType": "authorization_code",
  "tokenUrl": "https://auth.example.com/oauth/token",
  "authorizationUrl": "https://auth.example.com/oauth/authorize",
  "clientId": "your-client-id",
  "redirectUri": "https://your-app.com/callback",
  "code": "authorization-code-from-callback",
  "codeVerifier": "pkce-code-verifier"
}

get_auth_status

Returns the current authentication configuration (credentials are redacted).

clear_auth

Removes the current authentication configuration.

refresh_token

Manually refreshes the OAuth2 access token (when using OAuth2 authentication).

set_base_url

Sets a base URL for all subsequent requests.

{
  "url": "https://api.example.com/v1"
}

set_default_headers

Sets headers that will be included in all requests.

{
  "headers": {
    "Accept": "application/json",
    "X-App-Version": "1.0.0"
  }
}

get_request_history

Retrieves the history of recent requests.

{
  "limit": 10
}

Or get a specific request by ID:

{
  "requestId": "uuid-of-request"
}

clear_history

Clears the request history.

get_oauth2_authorization_url

Generates an OAuth2 authorization URL for the authorization code flow.

{
  "authorizationUrl": "https://auth.example.com/authorize",
  "clientId": "your-client-id",
  "redirectUri": "https://your-app.com/callback",
  "scope": "openid profile email",
  "usePkce": true
}

📝 Usage Examples

Example 1: Simple API Call with Bearer Token

User: Make a GET request to https://api.github.com/user with my token "ghp_xxxx"

1. First set authentication:
   set_auth({ "type": "bearer", "token": "ghp_xxxx" })

2. Make the request:
   make_request({ "method": "GET", "url": "https://api.github.com/user" })

Example 2: OAuth2 Authentication Flow

User: I need to access an API that uses OAuth2 with username/password

1. Configure OAuth2 with password grant:
   set_auth({
     "type": "oauth2",
     "grantType": "password",
     "tokenUrl": "https://api.example.com/oauth/token",
     "username": "[email protected]",
     "password": "mypassword",
     "clientId": "my-app",
     "scope": "read write"
   })

2. Make authenticated request (token is automatically obtained):
   make_request({ "method": "GET", "url": "https://api.example.com/data" })

Example 3: POST with JSON Body

User: Create a new user via POST

make_request({
  "method": "POST",
  "url": "https://api.example.com/users",
  "body": {
    "name": "John Doe",
    "email": "[email protected]",
    "role": "admin"
  },
  "headers": {
    "Content-Type": "application/json"
  }
})

🔒 Security Features

Credential Redaction

• All sensitive data (tokens, passwords, API keys) are redacted in logs and history
• Authorization headers are masked when viewing request history

PKCE Support

• OAuth2 authorization code flow supports PKCE (Proof Key for Code Exchange)
• Code verifiers and challenges are automatically generated

URL Validation

• Optional SSRF protection (can reject private IPs and localhost)
• Protocol validation (default: HTTP/HTTPS only)

Token Management

• Automatic token refresh before expiration
• Concurrent refresh request deduplication
• Secure in-memory token storage

🧪 Development

Building from Source

# Clone the repository
git clone https://github.com/dilina0914/api-client-mcp.git
cd api-client-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Testing

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run tests in watch mode
npm run test:watch

📁 Project Structure

api-client-mcp/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── auth/
│   │   ├── index.ts      # Auth exports
│   │   ├── oauth2.ts     # OAuth2 client implementation
│   │   └── token.ts      # Token manager
│   ├── http/
│   │   ├── index.ts      # HTTP exports
│   │   └── client.ts     # HTTP client implementation
│   ├── types/
│   │   └── index.ts      # TypeScript type definitions
│   └── utils/
│       ├── security.ts   # Security utilities
│       └── validation.ts # Input validation
├── tests/
│   ├── setup.ts          # Test setup
│   ├── auth.test.ts      # Authentication tests
│   ├── http.test.ts      # HTTP client tests
│   ├── security.test.ts  # Security utility tests
│   └── validation.test.ts # Validation tests
├── package.json
├── tsconfig.json
├── jest.config.js
└── README.md

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Support

If you encounter any issues or have questions, please open an issue on GitHub.