> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-ai-gateway/user-guide/mcp-servers.md).

# MCP servers

Putting approved tool servers behind one MCP address.

The MCP gateway keeps a registry of approved MCP servers and serves their tools through one endpoint. A client configures one address instead of one per tool server, and the credentials each tool server needs stay in the gateway.

Every call below is exercised by the smoke test against the reference deployment.

## Sign in

The admin UI is at `http://localhost:4444/admin`; sign in with `MCP_ADMIN_EMAIL` and `MCP_ADMIN_PASSWORD` from `.env`. For the API, mint a short-lived admin token:

```bash
cd deploy/compose
TOKEN=$(docker compose exec -T mcp-gateway python3 -m mcpgateway.utils.create_jwt_token \
  --username "$MCP_ADMIN_EMAIL" --exp 60 --secret "$MCP_JWT_SECRET_KEY" | tail -1)
```

A call without a token is refused with HTTP 401.

## Let the gateway reach the tool servers

The gateway refuses to call private and local addresses unless they are allowed, so a misconfigured or malicious registration cannot turn it into a door to the rest of the network. List the networks where approved tool servers run in `.env`:

```bash
MCP_ALLOWED_NETWORKS=["10.20.0.0/16"]
```

The reference deployment allows only its own compose network.

## Register a server

A server reachable over Streamable HTTP or SSE:

```bash
curl -s localhost:4444/gateways \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{ "name": "issue-tracker", "url": "http://issue-tracker-mcp.internal:9100/mcp", "transport": "STREAMABLEHTTP" }'
```

The gateway connects, discovers the server's tools, resources and prompts, and adds them to the registry. Tools are named `<server>-<tool>`, for example `issue-tracker-search`. A URL can be registered only once.

A server that speaks only stdio is put behind the gateway with `mcpgateway.translate`, which exposes it over HTTP.

## Hand clients a curated set

A **virtual server** groups chosen tools, from any registered servers, under one endpoint:

```bash
curl -s localhost:4444/servers \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{ "server": { "name": "coding-agents", "associated_tools": ["<tool id>", "<tool id>"] } }'
```

The answer carries the server's `id`; its endpoint is `/servers/<id>/mcp`. Give each audience its own virtual server – one for coding agents, one for an internal assistant – rather than exposing the whole registry.

## Connect a client

```bash
claude mcp add --transport http visdom-tools http://localhost:4444/servers/<id>/mcp \
  --header "Authorization: Bearer <client token>"
```

Any client that speaks MCP Streamable HTTP connects the same way. By default the gateway answers statelessly with JSON; set `USE_STATEFUL_SESSIONS=true` on the `mcp-gateway` service for SSE streams and sessions.

## What comes next

Today the registry is managed in the MCP gateway itself, and anyone with a valid token can call any tool in a virtual server they can reach. The [roadmap](/visdom-ai-gateway/roadmap.md) moves the approved-server catalogue into Git with pull-request review, puts Policy Gate in front of every tool call with access decided per team and per tool, and adds per-user OAuth so each call runs with the caller's own identity.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.visdom.virtuslab.com/visdom-ai-gateway/user-guide/mcp-servers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.