Configure base URL / path prefix for LangGraph Agent Server behind reverse proxy

LangSmith Product Help
1

Hi,

I’m running the LangGraph Agent Server using the official Docker image behind a reverse proxy with a path prefix.

Context

My public endpoint is:

<<host>>/api/agent-server

The proxy forwards requests to the agent server container.

Issue

The A2A card returned by the server contains URLs like:

<<host>>/a2a/{id}

However, the actual working URL is:

<<host>>/api/agent-server/a2a/{id}

So the /api/agent-server prefix is missing in generated URLs.

Question

Is there a supported way to configure a base URL or path prefix for the Agent Server so that generated URLs (like A2A card URLs) include /api/agent-server?

Thanks!

2

Yes the Agent Server supports this via the MOUNT_PREFIX environment variable ( though available in self-hosted deployments only).

Set MOUNT_PREFIX to your path prefix and the server will mount all of its routes under that prefix. This means both incoming request routing and generated URLs (like A2A card links) will include the prefix.

docker run \
  -e MOUNT_PREFIX="/api/agent-server" \
  -e REDIS_URI="redis://..." \
  -e DATABASE_URI="postgres://..." \
  -e LANGSMITH_API_KEY="..." \
  -p 8124:8000 \
  my-agent-image

With MOUNT_PREFIX="/api/agent-server", the server’s routes become:

  • /api/agent-server/ok
  • /api/agent-server/a2a/{id}
  • /api/agent-server/.well-known/agent-card.json
  • etc.

And generated A2A card URLs will correctly include the prefix:

https://<host>/api/agent-server/a2a/{id}

Reverse proxy configuration

Since MOUNT_PREFIX makes the server expect the full prefixed path, your reverse proxy should pass the path through as-is (do not strip the prefix):

location /api/agent-server/ {
    proxy_pass http://agent-server:8000;          # NO trailing slash — preserves the full path
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
}

Relevant docs

3

Hello,

It almost work, but the URL generated in the agent-card.json does not include the prefix path.

I’m using Traeffik as reverse proxy.

Can you explain in this particular case what the Agent Server uses to include a prefix path?

4

Good observation - this appears to be a gap in how the Agent Server constructs URLs for agent-card.json.

Here’s what we know from the Agent Server changelog and environment variable docs:

What MOUNT_PREFIX does:
It mounts all server routes under the specified path prefix (e.g., /api/agent-server/ok, /api/agent-server/a2a/{id}, etc.). This handles request routing correctly.

What the server uses for agent card URLs:
Per changelog entry v0.7.38, the server reads X-Forwarded-Proto to determine the correct scheme (https vs http) in agent card URLs. However, there’s no documented mechanism for the path prefix being included in the generated url field of the agent card.

What you can try:

  1. Ensure your Traefik proxy forwards these headers:

    • X-Forwarded-Proto (confirmed to affect agent card scheme as of v0.7.38)
    • X-Forwarded-Host (for the correct public hostname)

  2. Make sure you’re on langgraph-api >= 0.7.38 to get the X-Forwarded-Proto support for agent cards.

  3. If the prefix is still missing from the generated agent card URL despite MOUNT_PREFIX being set, this may be a bug or missing feature – the server constructs the card URL from the incoming request but may not be incorporating MOUNT_PREFIX into the generated url field.

If the above doesn’t resolve it, I’d recommend filing a GitHub issue on langchain-ai/langgraph requesting that MOUNT_PREFIX be reflected in A2A agent card URL generation, or that a dedicated env var (e.g., PUBLIC_BASE_URL) be added for explicitly controlling the base URL in generated agent cards. This is a known pattern in the A2A ecosystem where agent cards advertise internal URLs instead of externally reachable ones when running behind proxies.

5

Thanks. I have interesting observations here.

First X-Forwarded-Proto is correctly used. If I configure it in my proxy the value is reflected to the generated URL.

Second, and maybe most important, generated URL includes the prefix when I test my application without a proxy (local container or using a k8s post-forward). Therefore the Agent Server includes a mechanism that uses the MOUNT_PREFIX to generate the agent card URLs. However, something in the proxy affects this mechanism.

6

That’s a very useful observation and it clarifies the issue further.

Since the agent card URLs do include the prefix when you access the server directly (without a proxy), the Agent Server is using MOUNT_PREFIX to construct URLs correctly. The problem is that something in the proxy setup overrides or bypasses this mechanism.

The most likely cause: your Traefik configuration is stripping the path prefix before forwarding the request to the server.

If you’re using Traefik’s stripPrefix middleware (JUST THINKING ABOUT A POSSIBILITY):

middlewares:
  strip-agent-server:
    stripPrefix:
      prefixes:
        - "/api/agent-server"

Then here’s what happens:

Client request:   GET /api/agent-server/.well-known/agent-card.json
                          ↓
Traefik strips:   GET /.well-known/agent-card.json     ← prefix removed
                          ↓
Server receives:  /.well-known/agent-card.json
                  Server sees no prefix in the request path,
                  so it generates URLs WITHOUT the prefix

When you hit the server directly (no proxy), the request arrives at /api/agent-server/.well-known/agent-card.json — the server sees the full path including the prefix it mounted via MOUNT_PREFIX, so it generates correct URLs.

The fix: Since MOUNT_PREFIX makes the server expect and serve routes under /api/agent-server/..., you should not strip the prefix in Traefik. Pass the full path through:

http:
  routers:
    agent-server:
      rule: "PathPrefix(`/api/agent-server`)"
      service: agent-server
      # No stripPrefix middleware

  services:
    agent-server:
      loadBalancer:
        servers:
          - url: "http://agent-server:8000"

This way the request arrives at the server with the full path intact, MOUNT_PREFIX matches it, and the generated agent card URLs will include the prefix – just like when you access the server directly.

TL;DR: MOUNT_PREFIX handles both routing and URL generation, but only when it sees the prefix in the incoming request path. If the proxy strips it, the server falls back to prefix-less URL generation. Remove stripPrefix from your Traefik config and let MOUNT_PREFIX handle everything.

7

I already checked this and the path is not stripped.

Actually, since MOUNT_PREFIX is set, stripping the path would cause the server to respond a 404 because it serves all the routes under /api/agent-server.

I played with my local container and tried to send requests with some modified headers. I finally reproduced the issue by adding a Host header to my request. When Host header is present, the prefix path is missing from the generated URL (while the Host value is correctly used to adjust the domain).

I filled an issue: MOUNT_PREFIX ignored in generated URLs for agent cards when Host header is set (reverse proxy scenario) · Issue #7390 · langchain-ai/langgraph · GitHub

8

Okay, thanks for opening the issue on the langgraph repo. Let’s keep this thread open as well for now.
I feel like one of the official team members will be better able to help you out now.
CC: @eyurtsev @mdrxy

9

Thanks for reporting. A workaround today is to set LANGGRAPH_API_URL, but we’ll push a fix.

1 Like
10

Thanks. It resolves the issue. Is it possible to document the LANGGRAPH_API_URLat Environment variables - Docs by LangChain ?