@stackable-labs/mcp-app-extension

MCP server exposing Stackable Labs extension-platform tools to AI agents (Claude Code, etc.). Supports both stdio (local process, SDK self-auth via OAuth) and streamable HTTP (deployed Lambda, Claude Code native OAuth) transports.

Transports

| Transport | Home | Auth flow | Best for | |-----------|------|-----------|----------| | HTTP (streamable) | Deployed at api-{stage}-use1.stackablelabs.io/mcp/app-extension | Claude Code native OAuth — SDK discovers .well-known/oauth-authorization-server via WWW-Authenticate header, stores token in keychain | Most users. Simplest to configure. | | stdio | Local process via pnpm dlx @stackable-labs/mcp-app-extension@latest | Package-level OAuth flow — spins up localhost callback listener, caches token to ~/.stackable/mcp-auth.json | Local dev, agent orchestration outside a Claude Code keychain |

Both transports expose the same tool surface: list_apps, list_extensions, get_extension, list_instances, plus SDK-only tools (list_skills, lookup_skill, validate_manifest, validate_permissions).

Claude Code .mcp.json config

Drop into your project root (or ~/.claude.json for user-scoped setup). Both entries can coexist — Claude Code routes tool calls per-server.

Dev (against deployed api-dev-use1.stackablelabs.io):

{
  "mcpServers": {
    "stackable-dev-http": {
      "type": "http",
      "url": "https://api-dev-use1.stackablelabs.io/mcp/app-extension"
    },
    "stackable-dev-stdio": {
      "type": "stdio",
      "command": "pnpm",
      "args": [
        "--config.dlx-cache-max-age=0",
        "dlx",
        "@stackable-labs/mcp-app-extension@latest"
      ],
      "env": {
        "MCP_API_BASE_URL": "https://api-dev-use1.stackablelabs.io/mcp",
        "ADMIN_API_BASE_URL": "https://api-dev-use1.stackablelabs.io/admin"
      }
    }
  }
}

Prod (defaults, no env vars needed):

{
  "mcpServers": {
    "stackable-http": {
      "type": "http",
      "url": "https://api-use1.stackablelabs.io/mcp/app-extension"
    },
    "stackable-stdio": {
      "type": "stdio",
      "command": "pnpm",
      "args": ["--config.dlx-cache-max-age=0", "dlx", "@stackable-labs/mcp-app-extension@latest"]
    }
  }
}

Env vars (stdio only)

Both optional — defaults point at prod. Override per-stage as needed.

| Env var | Default | Purpose | |---------|---------|---------| | MCP_API_BASE_URL | https://api-use1.stackablelabs.io/mcp | MCP host root. OAuth discovery URL is derived as ${mcpBase}/.well-known/oauth-authorization-server. | | ADMIN_API_BASE_URL | https://api-use1.stackablelabs.io/admin | Admin API endpoint for platform tool calls (list_apps, etc.). |

HTTP transport reads URLs from the deployed Lambda's env (set via CDK + packages/infra/cdk/.env.{stage} — not client-controlled).

Auth isolation

Stdio transport stores its token at ~/.stackable/mcp-auth.json. CLI (@stackable-labs/cli-app-extension) stores its token at ~/.stackable/auth.json. The two are independent — authenticating via stdio MCP does not affect CLI auth and vice versa. HTTP transport stores its token in the Claude Code keychain, completely separate from both file-based caches.

Development

pnpm --filter @stackable-labs/mcp-app-extension build     # tsup bundle
pnpm --filter @stackable-labs/mcp-app-extension test      # vitest
pnpm --filter @stackable-labs/mcp-app-extension typecheck

To test a local build via stdio, point the .mcp.json command/args at the built dist:

{
  "command": "node",
  "args": ["/absolute/path/to/packages/mcp/app-extension/dist/index.js"],
  "env": { "MCP_API_BASE_URL": "...", "ADMIN_API_BASE_URL": "..." }
}