Skip to main content
Glama
physics91

AI API MCP Server

by physics91

AI API MCP Server

A FastMCP-based Model Context Protocol (MCP) server that provides unified access to multiple AI APIs including OpenAI GPT, Google Gemini, Anthropic Claude, and xAI Grok.

📚 Documentation

Related MCP server: Outsource MCP

Features

  • Unified Interface: Single MCP interface for multiple AI providers

  • Multiple Providers: Support for OpenAI, Anthropic, Google, and xAI

  • Streaming Support: Real-time streaming responses from all providers

  • Model Comparison: Compare responses from multiple models simultaneously

  • Content Analysis: Analyze code, text, security, and performance

  • Content Generation: Generate code, documentation, and tests

  • Automatic Retry: Built-in retry logic with exponential backoff

  • Error Handling: Comprehensive error handling across all providers

Installation

Quick Install

Choose your preferred installation method:

npx @physics91org/ai-api-mcp

Using Bun

bunx @physics91org/ai-api-mcp

Using Docker

docker run -it --rm \
  -e OPENAI_API_KEY=your_key \
  -e ANTHROPIC_API_KEY=your_key \
  -e GOOGLE_API_KEY=your_key \
  -e GROK_API_KEY=your_key \
  ai-api-mcp

Using Docker Compose

# Clone the repository first
git clone https://github.com/yourusername/ai-api-mcp.git
cd ai-api-mcp

# Copy and edit .env file
cp .env.example .env

# Run with docker-compose
docker-compose up

Manual Installation

Prerequisites

  • Python 3.10 or higher

  • pip

Steps

  1. Clone the repository:

git clone https://github.com/yourusername/ai-api-mcp.git
cd ai-api-mcp
  1. Run the installation script:

Linux/macOS:

chmod +x install.sh
./install.sh

Windows:

python -m venv venv
venv\Scripts\activate
pip install -e .
  1. Set up environment variables:

cp .env.example .env
# Edit .env with your API keys

Development Installation

For development with hot-reload and editable installation:

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Linux/macOS:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

Configuration

Add your API keys to the .env file:

# AI API Keys
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
GOOGLE_API_KEY=your_google_api_key_here
GROK_API_KEY=your_grok_api_key_here

# Optional: Custom API endpoints
# OPENAI_BASE_URL=https://api.openai.com/v1
# GROK_BASE_URL=https://api.x.ai/v1

# Retry Configuration
MAX_RETRIES=3
RETRY_DELAY=1.0

Usage

Running the Server

Choose your preferred method to run the server:

Using NPX/Bunx (No installation required)

# With npx
npx @physics91org/ai-api-mcp

# With bunx  
bunx @physics91org/ai-api-mcp

Using Node.js

npm start
# or
node run.js

Using Python

python -m src.server

Using Shell Script

./run.sh

Using Docker

# Build and run
docker build -t ai-api-mcp .
docker run -it --rm --env-file .env ai-api-mcp

# Or use docker-compose
docker-compose up

Available Tools

1. Chat

Send messages to AI models and get responses.

await mcp.chat(
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "Hello!"}
    ],
    model="gpt-4",
    temperature=0.7,
    max_tokens=1000
)

2. List Models

Get all available models from configured providers.

models = await mcp.list_models()

3. Compare

Compare responses from multiple models.

await mcp.compare(
    prompt="Explain quantum computing",
    models=["gpt-4", "claude-3-opus-20240229", "gemini-pro"],
    temperature=0.7
)

4. Analyze

Analyze content with specific focus.

await mcp.analyze(
    content="def factorial(n): return 1 if n <= 1 else n * factorial(n-1)",
    analysis_type="code",  # options: code, text, security, performance, general
    model="gpt-4"
)

5. Generate

Generate content of specific types.

await mcp.generate(
    prompt="Create a REST API for user management",
    generation_type="code",  # options: code, text, documentation, test
    model="gpt-4",
    language="python",
    framework="FastAPI"
)

Supported Models (2025)

OpenAI

Flagship GPT Models

  • gpt-4.1 - 1M context, multimodal with massive context

  • gpt-4o - 128K context, fast, intelligent, flexible

  • gpt-4o-audio-preview - 128K context, audio inputs/outputs

  • chatgpt-4o-latest - 128K context, ChatGPT version

Cost-Optimized Models

  • gpt-4.1-mini - 1M context, fast multimodal

  • gpt-4.1-nano - 1M context, ultra-fast

  • gpt-4o-mini - 128K context, fast and affordable

  • gpt-4o-mini-audio-preview - 128K context, audio support

Reasoning Models (o-series)

  • o4-mini - 200K context, faster reasoning

  • o3 - 200K context, most powerful reasoning

  • o3-pro - 200K context, deep thinking

  • o3-mini - 200K context, small reasoning alternative

  • o1 - 200K context, previous reasoning model

  • o1-mini - 128K context, small reasoning alternative

  • o1-pro - 200K context, enhanced reasoning

Older Models

  • gpt-4-turbo, gpt-4, gpt-3.5-turbo

Anthropic

Claude 4 Models (Latest Generation)

  • claude-opus-4-20250514 - Most powerful and capable model (32K output)

  • claude-sonnet-4-20250514 - High-performance with exceptional reasoning (64K output)

Claude 3.x Models

  • claude-3-7-sonnet-20250219 - High intelligence with extended thinking (64K output)

  • claude-3-5-sonnet-20241022 - Previous intelligent model v2 (8K output)

  • claude-3-5-sonnet-20240620 - Previous intelligent model (8K output)

  • claude-3-5-haiku-20241022 - Fastest model with intelligence (8K output)

  • claude-3-haiku-20240307 - Fast and compact for quick responses (4K output)

Google

Gemini 2.5 Series (Latest with Thinking)

  • gemini-2.5-pro - 1M context, advanced reasoning with deep thinking

  • gemini-2.5-flash - 1M context, fast advanced reasoning with thinking

  • gemini-2.5-flash-lite-preview-06-17 - 1M context, ultra-fast and cost-effective

Gemini 2.0 Series

  • gemini-2.0-flash - 1M context, real-time multimodal capabilities

  • gemini-2.0-flash-lite - 1M context, cost-effective and fast

Gemini 1.5 Series (Deprecated)

  • gemini-1.5-flash - 1M context, fast multimodal (deprecated)

  • gemini-1.5-flash-8b - 1M context, high volume processing (deprecated)

  • gemini-1.5-pro - 2M context, complex reasoning (deprecated)

xAI

Grok 4 Series (Latest Reasoning Models)

  • grok-4-0709 - 256K context, advanced reasoning with function calling

Grok 3 Series

  • grok-3 - 131K context, vision and function calling capabilities

  • grok-3-mini - 131K context, fast and efficient reasoning

  • grok-3-fast - 131K context, high-speed processing with regional availability

  • grok-3-mini-fast - 131K context, ultra-fast efficient processing

Grok 2 Series (Vision Models)

  • grok-2-vision-1212 - 32K context, vision capabilities with function calling

MCP Client Support

This server works with multiple MCP-supporting tools. See our MCP Installation Guide for detailed setup instructions.

Supported Clients

  • Claude Code (CLI) - Anthropic's official CLI with MCP support

  • Claude Desktop - Native desktop app with MCP integration

  • Cursor IDE - AI-powered IDE with built-in MCP support

  • VS Code - Via GitHub Copilot Chat extension

  • Windsurf Editor - Next-gen editor with MCP capabilities

  • Continue Extension - Open-source AI code assistant

  • And more...

Quick Configuration Example

{
  "mcpServers": {
    "ai-api": {
      "command": "npx",
      "args": ["@physics91org/ai-api-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-key",
        "ANTHROPIC_API_KEY": "your-key",
        "GOOGLE_API_KEY": "your-key",
        "GROK_API_KEY": "your-key"
      }
    }
  }
}

Development

Project Structure

ai-api-mcp/
├── src/
│   ├── server.py           # FastMCP server implementation
│   ├── provider_manager.py # Manages all AI providers
│   ├── models.py          # Pydantic models
│   ├── utils.py           # Utility functions
│   └── providers/         # AI provider implementations
│       ├── base.py
│       ├── openai_provider.py
│       ├── gemini_provider.py
│       ├── anthropic_provider.py
│       └── grok_provider.py
├── .env.example
├── pyproject.toml
└── README.md

Adding New Providers

  1. Create a new provider class in src/providers/

  2. Inherit from AIProviderBase

  3. Implement required methods: chat, list_models, validate_model

  4. Add provider to ProviderManager in provider_manager.py

License

MIT License

Contributing

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

Available Tools

5 tools
analyzeAnalyzeC

Analyze content using AI models

ParametersJSON Schema
NameRequiredDescriptionDefault
modelYesModel ID to use
contentYesContent to analyze
providerNoOptional provider name
analysis_typeYesType of analysis ('code', 'text', 'security', 'performance', 'general')

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description says nothing about required permissions, rate limits, output format, model selection implications, or side effects. 'Analyze content using AI models' is a tautology that provides no behavioral context whatsoever.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single seven-word sentence – extremely concise. However, its brevity comes at the cost of under-specification rather than efficient information delivery. It is front-loaded but contains no actionable detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 4 parameters (3 required), no annotations, and an output schema. The description does not compensate for the missing annotations by explaining the AI model interaction, expected latency, or result format. Even with an output schema covering return values, the description is too thin for a multi-purpose AI tool with a generic name.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are documented in the schema itself – including the analysis_type enum-like list and the optional provider field. The description adds no parameter meaning beyond the schema. Per rubric, baseline 4 applies for zero params, but here we have 4 params fully covered; a 3 reflects that the description contributes nothing beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Analyze content using AI models' restates the tool name and title with a vague verb. It does specify the resource ('content') and mechanism ('AI models'), but 'analyze' is an umbrella term that doesn't distinguish this from siblings like 'chat' or 'generate'. An agent cannot confidently choose this over 'compare' or 'generate' based on the description alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives. Siblings include 'compare', 'chat', 'generate', and 'list_models' – all potentially overlapping AI operations. The description never mentions these alternatives or the conditions under which 'analyze' is the correct choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

chatChatC

Chat with AI models from various providers

ParametersJSON Schema
NameRequiredDescriptionDefault
modelYesModel ID (e.g., 'gpt-4', 'claude-3-opus', 'gemini-pro')
streamNoWhether to stream the response
messagesYesList of message dicts with 'role' and 'content'
providerNoOptional provider name ('openai', 'anthropic', 'google', 'grok')
max_tokensNoMaximum tokens to generate
temperatureNoSampling temperature (0.0-2.0)

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about latency, cost, rate limits, error behavior, or what streaming does to the response shape. The single sentence adds essentially no behavioral context for a network-calling mutation-like operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One short, front-loaded sentence with zero waste, but for a six-parameter tool with an output schema it is under-specified rather than genuinely concise. Brevity here reflects missing content, not editorial discipline.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema and full parameter descriptions reduce some burden, but the description supplies no usage context, no provider/model selection logic, and no behavioral notes for a tool that fans out to multiple external AI providers. It is not complete enough to guide confident invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents model, messages, stream, provider, max_tokens, and temperature. The description adds no parameter meaning beyond that, which earns the baseline 3 rather than credit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a verb+resource ('chat with AI models') but is generic and does not differentiate this tool from siblings like 'generate' or 'compare', which plausibly overlap. An agent cannot tell from the text whether this is single-turn, multi-turn, or streaming-oriented.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus 'generate', 'compare', or 'analyze'. The mention of 'various providers' hints at breadth but does not specify any selection criteria or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compareCompareC

Compare responses from multiple AI models

ParametersJSON Schema
NameRequiredDescriptionDefault
modelsYesList of model IDs to compare
promptYesThe prompt to send to all models
max_tokensNoMaximum tokens to generate
temperatureNoSampling temperature

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden but only states the basic action. It does not disclose cost implications of calling multiple models, execution order, concurrency, or error handling when a model fails. The presence of an output schema slightly lowers the need to explain return values, but operational behavior remains undocumented.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words, though it is arguably too terse for a tool with four parameters and cross-model behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool that fans out to multiple models, the description omits key operational context such as whether calls happen in parallel, how results are aggregated, and any rate or cost considerations. With no annotations and no output details in the description, it is under-specified despite a clean schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters including prompt, models, max_tokens, and temperature are already documented. The description adds no parameter detail beyond what the schema provides; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (compare) and resource (responses from multiple AI models), which is clear and distinguishable from siblings generate and chat. It does not, however, explain how the comparison is presented or why one would use this over analyze.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings like generate, chat, or analyze is provided. The agent is left to infer that this is a multi-model comparative call from the description alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generateGenerateC

Generate content using AI models

ParametersJSON Schema
NameRequiredDescriptionDefault
modelYesModel ID to use
promptYesGeneration prompt
languageNoProgramming language (for code generation)
providerNoOptional provider name
frameworkNoFramework/library (for code generation)
generation_typeYesType of generation ('code', 'text', 'documentation', 'test')

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and discloses almost nothing: no side-effect profile, no auth/permission requirements, no cost or rate-limit implications, no note about model/provider selection behavior. It repeats only that models are involved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single short sentence with no padding, but it is so thin that concision comes at the cost of usefulness for a tool with six parameters. Appropriately front-loaded but under-specified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter tool with three required inputs and no annotations, the description omits far too much: no mention of the required fields, the generation_type options, or how it differs from 'chat'. The existence of an output schema excuses it only from explaining return values, not from this gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the six parameters (including the required prompt, generation_type, and model, and the generation_type value list) are already documented in the schema. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a verb ("Generate") and a vague resource ("content") plus the mechanism ("using AI models"), but "content" is broad enough to overlap with the sibling 'chat', and nothing distinguishes this tool from it. The purpose is inferable but not sharp.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus the sibling tools 'chat', 'compare', or 'analyze', and no mention of any prerequisite or context. The agent is left to guess the routing entirely.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_modelsList ModelsB

List all available AI models from all configured providers

Returns: List of model information including ID, name, provider, and capabilities

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden, but this is a zero-parameter read-only listing with minimal risk. It discloses scope ('all configured providers') and the fields returned, yet says nothing about freshness, permissions, or whether unconfigured providers are surfaced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action in one sentence, followed by a compact return summary. The Returns block partially duplicates the output schema, which costs a little, but nothing is bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return values, and the operation is a simple no-arg list. It is nearly complete, missing only a note on how results should be used or how current the model list is.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to add meaning to and no schema coverage gap to compensate for.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('List all available AI models') and adds provider scope ('from all configured providers'). It is clear without naming a sibling, and no sibling (compare, analyze, chat, generate) overlaps in purpose, so explicit differentiation isn't needed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus the siblings or in what workflow context it belongs (e.g., before chat/generate to discover valid model IDs). Usage is only weakly implied by 'list all available.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.2.0
    • First observedanalyze
    • First observedchat
    • First observedcompare
    • First observedgenerate
    • First observedlist_models

TDQS

C2.7/5.0

Scored across 5 tools

Disambiguation2/5

analyze and generate both use AI models and could be confused with each other or with chat; their boundaries are unclear from names and descriptions, making it hard to predict which tool to use for tasks like summarization versus creation.

Naming Consistency3/5

Four tools use bare verbs (compare, analyze, chat, generate) while one uses a verb_noun pattern (list_models), creating a mixed convention that is readable but inconsistent.

Tool Count4/5

Five tools is reasonable for an AI API wrapper, covering core operations without excessive bloat, though it leans slightly thin given the breadth of possible AI interactions.

Completeness3/5

The surface covers listing, chatting, generating, analyzing, and comparing, but lacks key lifecycle operations such as getting provider quota or model details, and there is no explicit create/delete to round out CRUD.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers