---
name: bijection-convex-mcp-gateway
description: "Evaluate and integrate the Convex MCP Gateway component with Bijection."
---

# Convex MCP Gateway

Auth-aware MCP server for Convex: expose Convex functions as MCP tools with per-tool scopes, OAuth 2.1 discovery, optional DCR bridge, and audit log.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-mcp-gateway
- Source: https://github.com/tfohlmeister/convex-mcp-gateway
- npm: https://www.npmjs.com/package/convex-mcp-gateway
- Directory: https://bijection.com/components/convex-mcp-gateway

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-mcp-gateway. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Convex MCP Gateway. Follow the installation and configuration steps exactly.

# Convex MCP Gateway

## Instructions

An auth-aware MCP (Model Context Protocol) server component that exposes Convex functions as MCP tools for AI agents. Provides OAuth 2.1 protected-resource discovery, per-tool authorization with scopes/roles, comprehensive audit logging, and wire-error sanitization. Built as a Convex Component with type-safe tool registration and full integration with Convex's existing auth system.

### Installation

```bash
npm install convex-mcp-gateway
```

Current npm version: `convex-mcp-gateway@2.1.1`

## Use cases

- **Expose internal APIs to AI agents** - Transform your existing Convex queries/mutations into MCP tools that Claude, GPT, or custom agents can discover and call with proper authentication

- **Build role-based agent workflows** - Create different tool catalogs for different user roles, where agents only see and can invoke functions their authenticated user has permission to access

- **Audit AI agent interactions** - Track every tool call with detailed logging including argument redaction, identity context, and error details for compliance and debugging

- **Bridge existing auth systems with MCP** - Use your current Clerk/Auth0/custom JWT setup without changes while providing OAuth 2.1 discovery for MCP clients

- **Prototype agent integrations locally** - Test full MCP workflows in development with the included convex-test helper for end-to-end testing

## How it works

You register Convex functions as MCP tools using `defineMcpQuery`, `defineMcpMutation`, or `defineMcpAction` with type-safe argument validation and optional metadata for authorization. The component handles the complete MCP 2025-06-18 Streamable HTTP protocol including session management, content negotiation, and identity-bound cleanup.

A single `authorize` callback controls both tool visibility (`tools/list`) and execution (`tools/call`) using your existing `ctx.auth.getUserIdentity()` flow. The gateway automatically filters the tool catalog based on what each authenticated user can actually invoke, ensuring agents only see relevant capabilities.

The component mounts as a standard Convex httpAction in your router and provides OAuth 2.1 protected-resource discovery with RFC 9728 metadata endpoints and proper `WWW-Authenticate` headers. Every tool invocation gets logged to an audit table with configurable argument redaction, while wire errors are sanitized to prevent information leakage.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Convex MCP Gateway is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-mcp-gateway)
- [GitHub repository](https://github.com/tfohlmeister/convex-mcp-gateway)
- [Live demo](https://github.com/tfohlmeister/convex-mcp-gateway-demo/)
- [Convex Components Directory](https://www.convex.dev/components/convex-mcp-gateway)
- [Convex documentation](https://docs.convex.dev)