iMCP

iMCP is an MCP (Model Context Protocol) server that acts as a universal bridge between AI assistants and your existing backend services — whether they are legacy SOAP/WSDL systems, modern REST APIs, IBM AS400/IBMi platforms, SAP, Apigee-hosted APIs, mainframe services, or any HTTP-callable endpoint. It dynamically discovers operations from service contracts (WSDL, OpenAPI, or a lightweight MCP JSON spec), generates structured tool definitions, and brokers authenticated calls — turning your existing services into live AI tools in under an hour.

Originally built to modernize insurance systems without rewrites, iMCP is industry-agnostic. It works equally well in banking, healthcare, logistics, retail, manufacturing, government, or any domain where valuable business logic is locked inside systems that lack an AI-native interface.

Table of Contents

• Why iMCP
• Who Is iMCP For
• How It Works
• Architecture
• Key Features
• Tech Stack
• Quick Start
• Admin Portal Walkthrough
• Supported Spec Types
• MCP JSON Spec Format
• Authentication Types
• API Reference
• Security Model
• Configuration
• Connecting AI Assistants
• Representative Use Cases
• Project Structure
• License

Why iMCP

Organizations across every industry run on battle-tested legacy systems — IBMi/AS400, SAP, mainframes, SOAP services, proprietary REST APIs — that hold irreplaceable business logic built up over decades. These systems work, but they are completely invisible to modern AI assistants.

Whether you are in insurance, banking, healthcare, logistics, retail, or government, the challenge is the same: valuable domain knowledge is locked inside systems that cannot be queried conversationally. The traditional path to fixing this means multi-year rewrites costing millions. iMCP offers a different answer:

Real business impact (targets):

Who Is iMCP For

iMCP is built for any organization that has existing backend services — regardless of age, technology, or industry — and wants to make them accessible to AI assistants without a rewrite.

Industries

Compatible Backend Systems

iMCP works with any system that exposes a WSDL, OpenAPI spec, or a callable HTTP endpoint:

How It Works

Architecture

Component Diagram

File Structure

imcp/
├── views/
│   ├── mcp.py              # MCP JSON-RPC 2.0 endpoint (tools/list, tools/call)
│   └── admin/
│       ├── services.py     # Service catalog CRUD
│       ├── tools.py        # Tool registry + cache refresh
│       ├── test.py         # Test console execution
│       ├── status.py       # System health + metrics
│       ├── api_keys.py     # API key management
│       └── pages.py        # Portal page rendering
├── services/
│   ├── wsdl_parser.py      # WSDL / SOAP spec parsing
│   ├── openapi_parser.py   # OpenAPI 2.x / 3.x spec parsing
│   ├── mcp_json_parser.py  # Custom MCP JSON spec parsing
│   ├── schema_converter.py # XSD → JSON Schema conversion
│   ├── tool_generator.py   # MCPTool dataclass + generation pipeline
│   ├── executor.py         # Unified tool execution (test console path)
│   ├── openapi_executor.py # OpenAPI upstream HTTP calls
│   ├── mcp_json_executor.py# MCP JSON upstream HTTP calls
│   ├── auth_headers.py     # Auth header builder (sync + async)
│   ├── oauth.py            # OAuth2 client_credentials token cache
│   ├── encryption.py       # Fernet credential encryption at rest
│   ├── cache.py            # TTL tool cache service
│   ├── audit.py            # Structured audit event logging
│   ├── redaction.py        # PII / secret redaction in logs
│   └── health_checker.py   # Upstream service reachability probes
└── models/
    ├── service.py          # Service catalog model
    ├── tool_cache.py       # Cached tool definitions model
    └── audit.py            # Audit event model

Dual Execution Paths

Execution parity: The Admin Portal's Test Console and the live MCP endpoint both run through the same internal execution handler. What you test in the portal is exactly what an AI assistant will call in production — no surprises.

Key Features

{ "operations": ["searchPolicy", "getCustomer"] }

Tech Stack

Quick Start

Prerequisites

• Python 3.11+
• Git

1 — Clone and set up the environment

git clone https://github.com/duvaragesh/iMCP.git
cd iMCP
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

2 — Configure environment variables

cp .env.example .env

Edit .env — full variable reference:

# Application
APP_NAME=iMCP
APP_VERSION=0.1.0
DEBUG=True                          # Set to False in production

# Database
DATABASE_URL=sqlite:///./imcp.db    # Swap to postgres://... for production

# Cache
CACHE_TTL_SECONDS=3600              # How long tool definitions are cached
CACHE_MAX_SIZE=1000                 # Max number of cached tool sets

# Rate Limiting
RATE_LIMIT_PER_MINUTE=100

# Authentication
JWT_SECRET=change-me-in-production-use-strong-secret   # Also used for Fernet encryption
JWT_ALGORITHM=HS256
# JWKS_URL=https://your-auth-provider.com/.well-known/jwks.json

# CORS
CORS_ORIGINS=["http://localhost:3000","http://localhost:8000"]

# Logging
LOG_LEVEL=INFO                      # DEBUG | INFO | WARNING | ERROR
LOG_FORMAT=json

# Redaction — fields scrubbed from all audit logs
REDACTION_PATTERNS=["password","token","secret","authorization","bearer","ssn","credit_card"]

# Observability (OpenTelemetry)
OTEL_ENABLED=false
# OTEL_ENDPOINT=http://localhost:4318

# Health Check
HEALTH_CHECK_INTERVAL_MINUTES=5

Important: JWT_SECRET is also used to derive the Fernet encryption key for stored service credentials. Use a strong random value and keep it consistent across restarts — changing it will invalidate all stored credentials.

3 — Initialize the database

python manage.py migrate

4 — Create a superuser (admin account)

python manage.py createsuperuser

You will be prompted for:

Username: admin
Email address: admin@example.com
Password: ••••••••
Password (again): ••••••••
Superuser created successfully.

This Django superuser is used to log in to the Admin Portal at /admin/login/. It is separate from iMCP API keys.

5 — Generate an iMCP API Key

Log in to the portal, go to Token Manager, and create an API key. This key is used to:

• Authenticate AI client calls to the MCP endpoint (/imcp/mcp)
• Authenticate calls to the Admin REST API (/imcp/admin/...)

Name:        my-claude-key
Description: Used by Claude Code MCP client
Roles:       admin

Copy the full key shown — it is only displayed once.

6 — Start the server

python manage.py runserver
# or with async/ASGI support
uvicorn config.asgi:application --reload

7 — Open the portal

• Login: http://localhost:8000/admin/login/
• Portal: http://localhost:8000/imcp/portal/

8 — Connect an AI client

# Claude Code CLI
claude mcp add --transport http iMCP http://localhost:8000/imcp/mcp \
  --header "Authorization: Bearer <your-api-key>" \
  --scope project

Run /mcp inside Claude Code to confirm iMCP is listed and tools are available.

Admin Portal Walkthrough

Adding Your First Service

1. Go to Services in the sidebar
2. Click + Add Service
3. Fill in:

4. Click Save — tools are generated and cached automatically

Verifying Generated Tools

1. Go to Tools in the sidebar
2. Select your service from the filter
3. Each tool shows its name, description, input schema, and cache status
4. Click Refresh on any service to re-parse its spec and regenerate tools

Testing a Tool

1. Go to Test Console in the sidebar
2. Select a tool from the dropdown
3. Fill in the arguments (JSON editor with schema hints)
4. Click Run — results show:
   • Normalized response
   • Raw upstream HTTP request/response (credentials redacted)
   • Correlation ID and latency

Monitoring Health

The Status page shows:

Supported Spec Types

# Register via API
POST /imcp/admin/services
{
  "name": "PolicySearch",
  "spec_type": "wsdl",
  "spec_url": "http://ibmi-host/wsservices/PolicySearch?wsdl",
  "auth_type": "basic",
  "auth_config": { "username": "svcuser", "password": "••••" }
}

POST /imcp/admin/services
{
  "name": "ClaimsAPI",
  "spec_type": "openapi",
  "spec_url": "https://api.internal/claims/openapi.yaml",
  "auth_type": "oauth2",
  "auth_config": {
    "token_url": "https://auth.example.com/token",
    "client_id": "imcp-client",
    "client_secret": "••••",
    "scope": "read:claims"
  }
}

MCP JSON Spec Format

{
  "name": "my-service-name",
  "version": "1.0.0",
  "description": "Brief description of what this service does",
  "tools": [
    {
      "name": "toolName",
      "description": "Describe what this tool does — this text is shown to the AI when selecting tools.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "param1": {
            "type": "string",
            "description": "Description of param1",
            "default": "optional-default-value"
          },
          "param2": {
            "type": "string",
            "description": "Description of param2"
          }
        },
        "required": ["param1"]
      },
      "endpoint": {
        "method": "GET",
        "baseUrl": "https://your-api-base-url.example.com",
        "path": "/your/api/path/",
        "queryParams": ["param1", "param2"]
      }
    }
  ]
}

Field reference:

Tip: Click Download JSON template in the Add/Edit Service modal (when MCP JSON is selected) to get a pre-filled template file.

Authentication Types

{ "token": "your-static-bearer-token" }

{ "username": "user", "password": "pass" }

{ "headers": { "X-API-Key": "abc123", "X-Tenant": "acme-corp" } }

{
  "token_url": "https://auth.example.com/oauth/token",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "scope": "read:policies"
}

iMCP Executor → oauth.py (cache miss?) → Token Endpoint
                     ↑                        ↓
               Token Cache ←────────── access_token
                     ↓
         Authorization: Bearer … → Upstream Service

API Reference

Request Flow

MCP Protocol Endpoint

POST /imcp/mcp
Content-Type: application/json
Authorization: Bearer <token>

List tools:

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }

Call a tool:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "searchPolicy",
    "arguments": { "policy-reference": "POL-20241001-001" }
  }
}

REST Convenience Endpoints

Admin API

All admin endpoints require Authorization: Bearer <token>.

Security Model

Credential Lifecycle

Register service (plaintext creds)
         ↓
  Fernet encrypt → store in DB
         ↓
  At call time: decrypt in memory → build auth header → call upstream
         ↓
  Discard decrypted value — never logged, never returned

Configuration

All settings are controlled via .env (copy from .env.example):

Scaling to Production

Connecting AI Assistants

Claude Code CLI

claude mcp add --transport http iMCP http://localhost:8000/imcp/mcp \
  --header "Authorization: Bearer <your-token>" \
  --scope project

Run /mcp in Claude Code to confirm iMCP is listed and tools are available.

VS Code (MCP Extension)

Add to .vscode/mcp.json:

{
  "servers": {
    "iMCP": {
      "type": "http",
      "url": "http://localhost:8000/imcp/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Any MCP-Compatible Client

iMCP implements the MCP JSON-RPC 2.0 protocol (protocol version: 2024-11-05). Any client that supports tools/list and tools/call over HTTP will work without modification.

Representative Use Cases

Project Structure

iMCP/
├── imcp/                       # Django application
│   ├── models/                 # Service, ToolCacheMetadata, AuditEvent, ApiKey
│   ├── views/
│   │   ├── mcp.py              # MCP JSON-RPC endpoint
│   │   └── admin/              # Portal API views
│   ├── services/               # Core business logic
│   ├── templates/imcp/         # HTMX + Tailwind portal templates
│   ├── migrations/             # Database migrations
│   ├── middleware/             # Correlation ID, auth middleware
│   └── management/commands/    # imcp_health_check management command
├── config/                     # Django settings, urls, wsgi
├── media/imcp_specs/           # Uploaded spec files (auto-cleaned on service delete)
├── docs/                       # Architecture SVG diagrams
│   ├── hero.svg
│   ├── stats.svg
│   ├── overview-flow.svg
│   ├── component-architecture.svg
│   └── request-flow.svg
├── iMCP_docs.html              # Full interactive documentation
├── .env.example                # Environment variable template
├── manage.py                   # Django management script
├── pyproject.toml              # Project dependencies
└── README.md

License

See LICENSE for full terms. For commercial licensing enquiries, open an issue on GitHub.