postgrest

This MCP server provides OAuth2-enabled authentication for PostgREST-backed APIs and is designed to work with any PostgREST server. Built with Hono, it supports Streamable HTTP and can be deployed across Supabase Edge Functions, Cloudflare Workers, or Deno Deploy. The MCP endpoint handles authentication, token validation, and authorization metadata integration between your OAuth provider and PostgREST. When running under Supabase Edge Functions, the server auto-detects the PostgREST endpoint and authentication setup via available environment variables. For non-Supabase deployments (Cloudflare or Deno), you must configure AUTH_SERVER_URL and API_BASE_URL (and optionally API_KEY or SUPABASE_ANON_KEY) to point to your OAuth server and PostgREST instance. The MCP endpoint is exposed at paths like /mcp on your deployment (for example, http://localhost:54321/functions/v1/postgrest-mcp/mcp on Supabase or http://localhost:8000/mcp for a local Deno setup). You can leverage the MCP Inspector during development to verify metadata and access controls, keeping in mind current RFC and header handling caveats noted in the project documentation.

Prerequisites:

• A running environment for your chosen deployment target (Supabase Edge Functions, Cloudflare Workers, or Deno Deploy).
• Access to a PostgREST server endpoint and an OAuth2 authorization server.
• Basic tooling depending on your deployment choice (Supabase CLI for Edge Functions, Cloudflare tooling for Workers, or Deno for Deno Deploy).

Install and run (example for a Node-based local setup; adapt to your environment):

1. Clone the repository: git clone https://github.com/your-org/semantius-postgrest-mcp.git cd semantius-postgrest-mcp

2. Install dependencies (adjust if you use PNPM/Yarn): npm install

3. Configure environment variables (example .env): AUTH_SERVER_URL=https://auth.example.com/oauth2 API_BASE_URL=https://api.example.com/rest/v1 API_KEY=your-api-key-if-needed SUPABASE_ANON_KEY=your-supabase-anon-key

4. Run locally (Node placeholder command): npm run start

5. Deploy to your target platform following the platform-specific steps described in the README (Supabase Edge Functions, Cloudflare Workers, or Deno Deploy).

Note: If you are deploying to Supabase Edge Functions, you may rely on SUPABASE_URL to auto-construct AUTH_SERVER_URL as {origin}/auth/v1. For Cloudflare and Deno Deploy, ensure AUTH_SERVER_URL and API_BASE_URL are explicitly provided.

Tips and caveats:

• The MCP endpoint will be hosted at /mcp on your deployment (for example, /mcp on Supabase Functions, /mcp on Cloudflare Workers, or /mcp on Deno Deploy).
• When running locally, you may access the MCP at http://localhost:8000/mcp (Deno) or the equivalent for your setup.
• If you encounter issues with OAuth metadata discovery, refer to the MCP Inspector compatibility note in the project documentation (RFC 9728 handling and WWW-Authenticate header nuances). This is particularly relevant when the metadata endpoint is served from uncommon paths.
• Environment variables are critical for non-Supabase deployments. Ensure AUTH_SERVER_URL and API_BASE_URL are reachable from your MCP server and that API_KEY or SUPABASE_ANON_KEY are set as needed.
• Supabase Edge Functions auto-detects the PostgREST endpoint and auth configuration; for other providers, you must supply explicit URLs.
• Supported deployment modes: Supabase Edge Functions (default auto-detection), Cloudflare Workers (environment-configuration required), Deno Deploy (environment-configuration required).