启用 MCP 服务器访问

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

在自托管 Supabase 中，MCP（模型上下文协议）服务器运行在内部 API 后面。目前，它不提供 OAuth 2.1 认证，也不打算对外公开。对应的 API 路径必须通过限制外部网络连接来保护。默认情况下，所有对 MCP 服务器的连接都会被拒绝。

🌐 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.

本指南解释了如何安全地启用对你自建的MCP服务器的访问。

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

安全注意事项 #

🌐 Security considerations

不要允许来自互联网的连接到自托管的MCP服务器。只能通过以下方式访问：

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

连接到运行 Studio 容器的服务器的 VPN
从你的本地电脑建立一个SSH隧道

通过 SSH 隧道访问 #

🌐 Accessing via SSH tunnel

步骤1：确定将用来访问MCP服务器的本地IP地址 #

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

通过 SSH 隧道连接到 Studio Docker 容器时，源 IP 会是 Docker 桥接网关的地址。你需要允许来自这个 IP 地址的连接。

🌐 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.

在运行你 Supabase 容器的主机上确定 Docker 桥接网关 IP：

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

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

这个命令会输出一个 IP 地址，例如 172.18.0.1。

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

步骤2：允许来自网关IP的连接 #

🌐 Step 2: Allow connections from the gateway IP

通过编辑 ./volumes/api/kong.yml 中的以下部分，将你发现的 IP 地址添加到 Kong 配置中：

🌐 Add the IP address you discovered to the Kong configuration by editing the following section in ./volumes/api/kong.yml:

把请求终止部分注释掉
从以 - name: cors 开始的整个部分删除 # 符号，包括 deny: []
把你的本地 IP 加到“允许”列表里
保留现有的缩进 - YAML 对空格非常敏感，如果修改了缩进，配置将无法加载
你编辑后的配置应该看起来像下面的例子：

volumes/api/kong.yml

1
## MCP endpoint - local access
2
3
- name: mcp
4
  _comment: 'MCP: /mcp -> http://studio:3000/api/mcp (local access)'
5
  url: http://studio:3000/api/mcp
6
  routes:
7
    - name: mcp
8
      strip_path: true
9
      paths:
10
        - /mcp
11
  plugins:
12
    # Block access to /mcp by default
13
    #- name: request-termination
14
    #  config:
15
    #    status_code: 403
16
    #    message: "Access is forbidden."
17
    # Enable local access (danger zone!)
18
    # 1. Comment out the 'request-termination' section above
19
    # 2. Uncomment the entire section below, including 'deny'
20
    # 3. Add your local IPs to the 'allow' list
21
    - name: cors
22
    - name: ip-restriction
23
      config:
24
        allow:
25
          - 127.0.0.1
26
          - ::1
27
          # Add your Docker bridge gateway IP below
28
          - 172.18.0.1
29
        # Do not remove deny!
30
        deny: []

步骤 3：重启 API 网关 #

🌐 Step 3: Restart API gateway

在你按上面的方法添加本地 IP 地址后，重启你的网关：

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

1
sh run.sh restart kong

第4步：创建SSH隧道 #

🌐 Step 4: Create the SSH tunnel

在你的本地机器上，创建一个到 Supabase 主机的 SSH 隧道：

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

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

这个命令会把本地端口 8080 转发到你 Supabase 主机上的端口 8000。

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

第5步：配置你的MCP客户端 #

🌐 Step 5: Configure your MCP client

编辑你的 MCP 客户端设置，并将以下内容添加到 "mcpServers": {} 或 "servers": {}：

🌐 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
}

步骤 6：开始使用自托管的 MCP 服务器 #

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

在你的本地电脑上，检查 MCP 服务器是否可以访问：

🌐 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
  }'

启动你的 MCP 客户端（Claude Code、Cursor 等）并验证对 MCP 工具的访问。例如，你可以问：“什么是 Supabase 匿名密钥？使用 Supabase MCP 服务器工具。”

🌐 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

如果你无法连接到 MCP 服务器：

🌐 If you are unable to connect to the MCP server:

将 Kong 配置文件更新到最新版本并小心编辑
确认 Docker 桥接网关 IP 是否已正确添加在 ./volumes/api/kong.yml
检查 Kong 的日志是否有错误：docker compose logs kong
确保你的 SSH 隧道是激活的