Interface types

Every extension declares one or more interfaces. The interface dictates how godmode dispatches calls and what --help looks like at the inner levels.

At a glance

Interface	Source of truth	Best for	Live example
`api`	OpenAPI 3.x spec	REST APIs (most third-party services)	stripe, openai, slack, petstore
`graphql`	SDL file or introspectable endpoint	GraphQL APIs	github
`mcp`	MCP server (stdio or HTTP)	Existing MCP servers, custom tooling	context7, claude-code-channels

Decision tree

Does the upstream publish an OpenAPI 3.x spec?
├── Yes → api
└── No
    ├── Is it GraphQL?
    │   ├── Yes → graphql
    │   └── No
    └── Is there already an MCP server for it?
        ├── Yes → mcp (point at the existing server)
        └── No → write your own MCP server in a package, declare type=mcp,
                 OR file a feature request upstream for an OpenAPI spec

`api` (REST)

Routes derived from an OpenAPI 3.x document. godmode parses paths, methods, parameters, and request/response shapes — --help shows them all.

interfaces:
  api:
    spec: https://example.com/openapi.yaml
    url:  https://api.example.com

Strengths: zero runtime code, automatic parameter validation, --help doubles as API documentation.

Limits: only as good as the upstream spec. Missing operationIds, vague descriptions, or missing examples mean less helpful --help output. (godmode synthesizes operationIds from method+path when missing.)

`graphql`

Either a local SDL file or an introspectable endpoint.

# SDL-based
interfaces:
  graphql:
    spec: ./schema.graphql

# Introspection-based
interfaces:
  graphql:
    url: https://api.github.com/graphql

Strengths: schema awareness; users can ask --help for a type or field. Single endpoint, no per-route parsing.

Limits: introspection requires network access at install time and may be disabled for private GraphQL APIs (you'll need to ship the SDL with the package).

`mcp` (Model Context Protocol)

For wrapping existing MCP servers, or for cases where the upstream tool surface is best modeled as MCP tools (not REST routes).

Spec-based (HTTP MCP server)

interfaces:
  mcp:
    url: https://example.com/mcp

godmode connects over HTTP, lists tools, exposes them as godmode <ext> mcp <tool> invocations.

Package-based (stdio MCP server)

For when the MCP server is itself a binary or script you ship in the same npm package:

interfaces:
  mcp:
    command: node
    args: ["dist/server.js"]

The package's package.json ships the binary; godmode spawns it on demand. See extensions/claude-code-channels for a complete example.

Multiple interfaces

You can declare more than one — useful when an API has both an OpenAPI spec and a richer MCP wrapper:

interfaces:
  api:    { spec: ... }
  mcp:    { command: node, args: [...] }

Then both godmode myext api ... and godmode myext mcp ... work. See Multi-interface extensions.

Derivative MCP serving

Even an api-only or graphql-only extension can be served as an MCP server without declaring mcp: — godmode <ext> mcp synthesizes one. See MCP serving for how the synthesis works.