ImageKit API MCP Server (Developer Guide)

This repository hosts the ImageKit MCP server implementation used to expose ImageKit capabilities to MCP clients (VS Code, Cursor, Claude Code, and other compliant clients).

The server supports two runtime modes:

1. Local stdio MCP server for direct client integration.
2. Remote HTTP MCP server with built-in OAuth 2.0 for multi-user deployments (for example EKS).

What Is MCP And What This Server Does

MCP (Model Context Protocol) is a standard way for LLM clients to call tools.

This server provides ImageKit operations through two MCP tools:

1. search_docs
2. execute

The common flow is:

1. Agent calls search_docs to discover the right SDK methods.
2. Agent calls execute with TypeScript code.
3. Server runs that code in an isolated Deno worker with an initialized ImageKit SDK client.
4. Worker output is returned as MCP tool result.

Repository Overview

• src/index.ts: entrypoint and transport selection.
• src/http.ts: HTTP transport, OAuth endpoints, bearer-token validation, MCP route handling.
• src/stdio.ts: stdio transport launcher.
• src/server.ts: MCP tool registration and request handlers.
• src/code-tool.ts: execute tool implementation (sandboxed code execution).
• src/docs-search-tool.ts: search_docs tool implementation (local docs index).
• src/oauth-store.ts: OAuth storage abstraction, in-memory store, Redis store.
• src/options.ts: CLI flags and env parsing.
• helm-chart/: Kubernetes chart for EKS-style deployments.
• .github/workflows/cd.yaml: CI/CD workflow (build, push, helm deploy).

Tools Exposed

search_docs

• Purpose: Search SDK documentation and examples.
• Input: query, language, optional detail.
• Behavior: Read-only local docs search.

execute

• Purpose: Execute TypeScript code against initialized @imagekit/nodejs client.
• Input: code, optional intent.
• Behavior:
  • Runs code in a Deno worker.
  • Network egress is constrained to ImageKit API host.
  • Returns console output and function return value.
  • Can block configured SDK methods.

Authentication And Credential Model

The server supports two auth models in HTTP mode:

1. OAuth 2.0 Authorization Code + PKCE (default, recommended for remote clients).
2. Legacy direct credential headers or environment variable.

OAuth Endpoints

• POST /register
• GET /authorize
• POST /approve
• POST /token
• GET /.well-known/oauth-authorization-server
• GET /.well-known/oauth-protected-resource

Aliases are also exposed under /mcp/.well-known/* to support clients expecting MCP-scoped metadata.

Credential Handling

At approval time, user enters ImageKit private key (and optional password). The server stores these in OAuth records and, on authenticated requests, hydrates request headers internally for SDK calls.

Store Behavior: Memory Vs Redis

• No REDIS_URL: in-memory store (InMemoryOAuthStore), suitable for local development/single-process use.
• With REDIS_URL: Redis-backed store (RedisOAuthStore), required for stable multi-pod or restart-safe deployments.

TTL Logic

• Authorization code TTL: 300 seconds (5 minutes).
• Access token TTL: configurable.
  • Default code fallback: 86400 seconds.
  • Recommended deployment override: OAUTH_ACCESS_TOKEN_TTL_SECONDS (for example 2592000 = 30 days).

Issuer URL Behavior (Important For Ingress)

Issuer/base URL is resolved in this order:

1. OAUTH_ISSUER if explicitly set.
2. Forwarded ingress headers (X-Forwarded-Proto, X-Forwarded-Host).
3. Request protocol + host.

This allows one image/chart to run across different exposed domains without hardcoding issuer in most ingress setups.

Running Locally

Prerequisites

1. Node.js 20+.
2. npm.
3. Deno installed (required by execute tool).
4. Optional: Redis (for OAuth persistence across restarts).

Install And Build

npm ci
npm run build

Run As Stdio MCP Server

export IMAGEKIT_PRIVATE_KEY="<your_private_key>"
node dist/index.js --transport stdio

Run As Remote HTTP MCP Server (OAuth enabled)

node dist/index.js \
  --transport http \
  --port 3001 \
  --redis-url redis://localhost:6379

Optional runtime env:

• OAUTH_ACCESS_TOKEN_TTL_SECONDS=2592000
• OAUTH_ISSUER=https://your-public-domain (usually not required if forwarded headers are correct)

Quick Local Health Checks

curl http://localhost:3001/health
curl http://localhost:3001/.well-known/oauth-authorization-server
curl -X POST http://localhost:3001/mcp -H 'content-type: application/json' -d '{}'

The last request should return the auth HTML when unauthenticated.

Running On Kubernetes (Helm)

Chart

• Chart path: helm-chart/
• Service name: imagekit-api-mcp-server-service

Deploy

helm upgrade imagekit-api-mcp-server ./helm-chart --install

Common production values:

1. Image repository/tag.
2. Redis host/port.
3. env.OAUTH_ACCESS_TOKEN_TTL_SECONDS.
4. Resource requests/limits.

Development Notes

• Build script: npm run build (uses ./build).
• Tests: npm test.
• Lint: npm run lint.
• HTTP default option in CLI is port 3000, but repo deployment examples commonly use 3001.

Security Notes

1. Use Redis in real deployments. In-memory OAuth store is not restart-safe.
2. Keep token TTL aligned with security requirements. Longer TTL reduces login prompts but increases token exposure window.
3. Prefer OAuth over static private-key env for multi-user remote access.
4. If deploying behind ingress, ensure forwarded headers are preserved.

CI/CD

The workflow in .github/workflows/cd.yaml is adapted for this repository and performs:

1. Node build/test.
2. Docker image build and push to ECR.
3. Helm deploy to stage/prod EKS clusters using repo variables/secrets.