apimcp

apimcp

Convert an OpenAPI document into an MCP server.

What it does

apimcp adapts an OpenAPI-described HTTP API into an MCP server. MCP clients can discover the API operations as tools and call the existing service without requiring a second hand-written MCP implementation.

Status

This is an MVP. It supports OpenAPI JSON/YAML, common HTTP methods, path and query/header parameters, JSON request bodies, Bearer tokens, API keys, stdio transport, and allow/deny tool filters. Path-level parameters are merged with operation parameters, and generated tool names are deterministic. Local $ref references are resolved through kin-openapi; external references are disabled by default. Tool calls also perform server-side checks for required parameters and common JSON types before contacting the upstream API.

Run

go run ./cmd/apimcp --spec openapi.yaml --base-url https://api.example.com

The project uses the official Go MCP SDK and adapts OpenAPI operations into MCP tools. It does not expose every operation automatically when --allow is set:

go run ./cmd/apimcp --spec openapi.yaml --allow getUser,listUsers --stdio

For an API key:

go run ./cmd/apimcp --spec openapi.yaml `
  --api-key-name X-API-Key `
  --api-key-value "$env:API_KEY" `
  --api-key-in header

For credentials stored in environment variables:

go run ./cmd/apimcp --spec openapi.yaml `
  --bearer-token-env API_TOKEN

go run ./cmd/apimcp --spec openapi.yaml `
  --api-key-value-env API_KEY `
  --api-key-name X-API-Key

The --stdio flag is accepted for compatibility with MCP client configurations; stdio is the default transport.

Library usage

spec, err := apimcp.LoadFile("openapi.yaml")
if err != nil {
    return err
}

return apimcp.RunStdio(ctx, spec, apimcp.Options{
    BaseURL:     "https://api.example.com",
    BearerToken: token,
})

Development

go test ./...
go test -race ./...
go vet ./...

The test suite includes an in-memory MCP client and an httptest upstream server to verify tool discovery, argument validation, request conversion, and error results end to end.

Roadmap

• External OpenAPI references and reusable schemas
• OpenAPI security scheme auto-detection
• OAuth authentication
• HTTP transport
• file upload/download handling
• generated tool documentation

Contributing

See CONTRIBUTING.md for the development workflow and commit conventions.