Enabling MCP Server Access

Configure secure access to the MCP server in your self-hosted Supabase instance.

The MCP (Model Context Protocol) server in self-hosted Supabase runs behind the internal API. Currently, it does not offer OAuth 2.1 authentication, and is not intended to be exposed to the Internet. The corresponding API route has to be protected by restricting network connections from the outside. By default, all connections to the MCP server are denied.

This guide explains how to securely enable access to your self-hosted MCP server.

Security considerations#

Do not allow connections to the self-hosted MCP server from the Internet. Only access it via:

A VPN connection to the server running the Studio container
An SSH tunnel from your local machine

Accessing via SSH tunnel#

Step 1: Determine the local IP address that will be used to access the MCP server#

When connecting via an SSH tunnel to the Studio Docker container, the source IP will be that of the Docker bridge gateway. You need to allow connections from this IP address.

Determine the Docker bridge gateway IP on the host running your Supabase containers:

1
docker inspect supabase-envoy \
2
  --format '{{range .NetworkSettings.Networks}}{{println .Gateway}}{{end}}'

This command will output an IP address, e.g., 172.18.0.1.

Step 2: Allow connections from the gateway IP#

Add the IP address you discovered to the Envoy configuration by editing the /mcp route in ./volumes/api/envoy/lds.template.yaml:

Find the route with prefix: /mcp
Comment out the rbac block that denies all traffic and uncomment the allow-list policy below
Keep loopback entries (127.0.0.1 and ::1) and add your Docker bridge gateway IP
Preserve the existing indentation - YAML is whitespace-sensitive and the config will fail to load if it changes
Your edited configuration should look like the example below:

volumes/api/envoy/lds.template.yaml

1
- match:
2
    prefix: /mcp
3
  route:
4
    cluster: studio
5
    prefix_rewrite: /api/mcp
6
    timeout: 30s
7
  request_headers_to_add:
8
    - header:
9
        key: X-Forwarded-Prefix
10
        value: /mcp
11
      append_action: ADD_IF_ABSENT
12
  typed_per_filter_config:
13
    envoy.filters.http.basic_auth:
14
      '@type': >-
15
        type.googleapis.com/envoy.config.route.v3.FilterConfig
16
      disabled: true
17
    envoy.filters.http.rbac:
18
      '@type': >-
19
        type.googleapis.com/envoy.extensions.filters.http.rbac.v3.RBACPerRoute
20
      # Block access to /mcp by default
21
      #rbac:
22
      #  rules:
23
      #    action: DENY
24
      #    policies:
25
      #      deny_all:
26
      #        permissions:
27
      #          - any: true
28
      #        principals:
29
      #          - any: true
30
      # Enable local access (danger zone!)
31
      # 1. Comment out the 'rbac' block above.
32
      # 2. Uncomment and adjust the 'rbac' block below.
33
      # 3. Add or adjust your local IPs in 'principals'.
34
      rbac:
35
        rules:
36
          action: ALLOW
37
          policies:
38
            allow_local:
39
              permissions:
40
                - any: true
41
              principals:
42
                - direct_remote_ip:
43
                    address_prefix: 127.0.0.1
44
                    prefix_len: 32
45
                - direct_remote_ip:
46
                    address_prefix: ::1
47
                    prefix_len: 128
48
                - direct_remote_ip:
49
                    # Add your Docker bridge gateway IP below
50
                    address_prefix: 172.18.0.1
51
                    prefix_len: 32

Step 3: Restart API gateway#

After you've added the local IP address as above, restart your gateway:

1
sh run.sh restart api-gw

Step 4: Create the SSH tunnel#

From your local machine, create an SSH tunnel to your Supabase host:

1
ssh -L localhost:8080:localhost:8000 you@your-supabase-host

This command forwards local port 8080 to port 8000 on your Supabase host.

Step 5: Configure your MCP client#

Edit the settings for your MCP client and add the following to "mcpServers": {} or "servers": {}:

1
{
2
  "mcpServers": {
3
    "supabase-self-hosted": {
4
      "url": "http://localhost:8080/mcp"
5
    }
6
  }
7
}

Step 6: Start using the self-hosted MCP server#

From your local machine, check that the MCP server is reachable:

1
curl http://localhost:8080/mcp \
2
  -X POST \
3
  -H "Content-Type: application/json" \
4
  -H "Accept: application/json, text/event-stream" \
5
  -H "MCP-Protocol-Version: 2025-06-18" \
6
  -d '{
7
    "jsonrpc": "2.0",
8
    "id": 1,
9
    "method": "initialize",
10
    "params": {
11
      "protocolVersion": "2025-06-18",
12
      "capabilities": {
13
        "elicitation": {}
14
      },
15
      "clientInfo": {
16
        "name": "test-client",
17
        "title": "Test Client",
18
        "version": "1.0.0"
19
      }
20
    }
21
  }'

Start your MCP client (Claude Code, Cursor, etc.) and verify access to the MCP tools. For example, you can ask: "What is Supabase anon key? Use the Supabase MCP server tools."

Troubleshooting#

If you are unable to connect to the MCP server:

Confirm the Docker bridge gateway IP is correctly added to the API gateway configuration
Check the API gateway's logs for errors: docker compose logs api-gw
Make sure your SSH tunnel is active