better mcp gateway/auth docs (#1580)

Author: samecrowder

src/langsmith/agent-builder-mcp-framework.mdx

@@ -120,3 +120,53 @@ Tools with `auth_provider` must:
 - Have `context: Context` as the first parameter
 - Specify at least one scope
 - Use `context.token` to make authenticated API calls
+
+## Using as an MCP gateway
+
+The LangSmith Tool Server can act as an MCP gateway, aggregating tools from multiple MCP servers into a single endpoint. Configure MCP servers in your `toolkit.toml`:
+
+```toml
+[toolkit]
+name = "my-toolkit"
+tools = "./my_toolkit/__init__.py:TOOLS"
+
+[[mcp_servers]]
+name = "weather"
+transport = "streamable_http"
+url = "http://localhost:8001/mcp/"
+
+[[mcp_servers]]
+name = "math"
+transport = "stdio"
+command = "python"
+args = ["-m", "mcp_server_math"]
+```
+
+All tools from connected MCP servers are exposed through your server's `/mcp` endpoint. MCP tools are prefixed with their server name to avoid conflicts (e.g., `weather.get_forecast`, `math.add`).
+
+## Custom authentication
+
+Custom authentication allows you to validate requests and integrate with your identity provider. Define an authentication handler in your `auth.py` file:
+
+```python
+from langsmith_tool_server import Auth
+
+auth = Auth()
+
+@auth.authenticate
+async def authenticate(authorization: str = None) -> dict:
+    """Validate requests and return user identity."""
+    if not authorization or not authorization.startswith("Bearer "):
+        raise auth.exceptions.HTTPException(
+            status_code=401,
+            detail="Unauthorized"
+        )
+
+    token = authorization.replace("Bearer ", "")
+    # Validate token with your identity provider
+    user = await verify_token_with_idp(token)
+
+    return {"identity": user.id}
+```
+
+The handler runs on every request and must return a dict with `identity` (and optionally `permissions`).