MCP Server
The SIMOSphere AI MCP (Model Context Protocol) server exposes the platform's capabilities as structured tools and resources that AI agents can discover and invoke programmatically. It implements the open MCP specification with support for both stdio and HTTP transport.
Installation
The MCP server is distributed as an npm package. You can run it directly via npx without installing, or add it as a project dependency:
# Run directly (no install needed)
npx @simosphere/mcp-server
# Or install globally
npm install -g @simosphere/mcp-server
# Or add to your project
npm install @simosphere/mcp-serverConfiguration
Add the MCP server to your agent's configuration file. The server authenticates using your SIMOSphere AI API key provided via the SIMOSPHERE_API_KEY environment variable:
{
"mcpServers": {
"simosphere": {
"command": "npx",
"args": ["@simosphere/mcp-server"],
"env": {
"SIMOSPHERE_API_KEY": "sk_live_YOUR_API_KEY",
"SIMOSPHERE_BASE_URL": "https://api.simosphereai.com/v1"
}
}
}
}The SIMOSPHERE_BASE_URL is optional and defaults to the production API. Override it for staging or local development environments.
Available Tools
The MCP server exposes the following tools that agents can discover and invoke. Each tool includes a JSON Schema definition for its input parameters and returns structured results.
chat_completion
Send a chat completion request to any available model. Supports system prompts, multi-turn conversations, temperature control, and max token limits. Returns the model response along with token usage statistics.
Parameters:
model: string — Model ID (e.g., "mistral-small-latest")
messages: Message[] — Array of {role, content} objects
temperature?: number — Sampling temperature (0.0–2.0, default 0.7)
max_tokens?: number — Maximum tokens to generate (default 1024)list_models
Retrieve a list of all models available on the current plan. Returns model IDs, display names, context window sizes, and pricing tiers. Use this tool to dynamically select the best model for a given task.
Parameters: (none)
Returns: Array of { id, name, context_window, pricing_tier }get_usage
Query token usage statistics for the current billing period. Returns prompt tokens, completion tokens, total tokens, and cost breakdown by model. Useful for budget monitoring and cost optimization within agent workflows.
Parameters:
period?: string — "day" | "week" | "month" (default "month")
Returns: { prompt_tokens, completion_tokens, total_tokens, cost_eur }check_health
Check the operational status of the SIMOSphere AI platform. Returns the health status of the API gateway, model backends, and database connections. Agents can use this tool to verify connectivity before initiating complex workflows.
Parameters: (none)
Returns: { status: "healthy" | "degraded" | "down", components: {...} }Resources
MCP resources provide read-only context that agents can access to inform their decisions. Unlike tools, resources do not perform actions — they expose configuration, documentation, and status information.
simosphere://configCurrent API configuration including the base URL, active plan, rate limits, and available model list.
simosphere://modelsDetailed model catalog with context windows, pricing, capabilities, and recommended use cases for each available model.
simosphere://usageReal-time usage dashboard data including tokens consumed, requests made, and remaining quota for the current billing period.
Transport Configuration
The MCP server supports two transport modes, each suited to different deployment scenarios:
stdio (Default)
The default transport communicates via standard input and output streams. This is the recommended mode for local development and single-agent setups. The MCP client spawns the server process and communicates via JSON-RPC messages on stdin/stdout.
HTTP with SSE
For remote deployments and multi-agent architectures, the server can run as an HTTP server with Server-Sent Events (SSE) for real-time streaming. This mode supports multiple concurrent connections and is suitable for containerized deployments:
# Start the MCP server in HTTP mode
SIMOSPHERE_API_KEY=sk_live_YOUR_KEY \
npx @simosphere/mcp-server --transport http --port 3300
# Connect from your MCP client configuration:
{
"mcpServers": {
"simosphere": {
"url": "http://localhost:3300/sse"
}
}
}Integration Patterns
The MCP server works with any MCP-compatible client. Here are common integration patterns:
Single Agent with Local MCP
The simplest setup: one agent connecting to the MCP server via stdio. The agent discovers available tools at startup and can invoke them throughout its execution. Ideal for CLI tools, scripts, and development workflows.
Multi-Agent with Shared MCP Server
Deploy the MCP server in HTTP mode and connect multiple agents to the same instance. Each agent receives its own session with independent state. Useful for orchestration platforms where multiple specialized agents need access to the same AI models.
IDE Integration
Add the MCP server to your IDE's configuration to enable AI-powered code assistance using SIMOSphere AI models. The server integrates with VS Code, Cursor, Windsurf, and any editor that supports the MCP protocol.
MCP Registries
The SIMOSphere AI MCP Server is listed on leading MCP registries. Browse the server profile for installation instructions, version history, and community reviews.