Fundamentals

Introduction

Organizations give their people and their agents access to tools: issue trackers, code hosts, documentation, internal APIs. Each tool lives behind its own server, with its own protocol, its own credentials and its own way to run. A tool server in Gatana is the object that describes one such resource. When you add a tool server to your gateway, its tools become available to the people, teams and agents you give access to, through one MCP endpoint.

Definitions

• MCP: the Model Context Protocol. The open protocol that AI clients such as Claude, Cursor and GitHub Copilot use to list and call tools.
• Tool server: provides tools in your gateway. It configuration describes how it runs, who may use it and which tools it exposes. The rest of the documentation calls it a server.
• Transport: the way Gatana talks to a server: a remote HTTP endpoint, an executable file Gatana starts, FaaS code Gatana runs, an OpenAPI specification or a built-in implementation.
• Tool: one function a server offers. Gatana caches the tool list of each server and exposes every tool to clients as {slug}_{toolname}.
• Slug: the short technical identifier of a server (a-z and hyphens). It is unique in the organization and it is prepended to each tool name.
• Credential: the resolved secret that Gatana uses when it calls a tool: an API key or an OAuth token. See Credentials.

What is a tool server?

A tool server is the unit you manage in the Gatana dashboard, the CLI and the public API. The server is the source of truth for everything the gateway needs in order to call its tools. Gatana discovers the tools, stores them, applies your overrides, checks who is calling, resolves the credentials, evaluates the firewall rules and returns the result to the client.

Whatever a server runs on, your AI clients see the same thing: one remote MCP endpoint that lists the tools of every server they have access to. Gatana supports these kinds of servers:

The kind only changes how Gatana talks to that one server. Everything else on this page applies to all of them.

Why use tool servers?

Without a gateway, each person connects each AI client to each MCP server by hand. API keys end up in configuration files on laptops, nobody can say which keys exist, and there is no record of what the agents did with them. Tool servers in Gatana replace that with one connection per client and central control over the rest:

• One endpoint. A client connects to the gateway once and gets every tool the user is allowed to use.
• Central credentials. Keys and OAuth tokens are stored in Gatana, shared for the whole server or held per user. They never reach the client.
• Access control. Membership and roles decide who can see a server and who can call its tools.
• Tool shaping. Disable tools, rename them, rewrite their descriptions and input schemas, so the model gets a tool list that fits the task.
• Guard rails. Firewall rules deny or log calls, compression keeps large outputs out of the context window, and every call is written to the audit log.

Building this yourself means a proxy, a secret store, an OAuth client, a policy engine and a log pipeline. Gatana handles that work so you only describe the server.

What your users experience

Consider a team that wants its agents to work with GitHub.

Your team does not use Gatana

1. Each developer finds the GitHub MCP server and installs it on their machine.
2. Each developer creates a personal access token on GitHub and pastes it into the configuration file of their AI client.
3. They repeat step 2 for every AI client they use.
4. A developer who wants a safer tool list removes tools by editing the configuration, if the client allows it.
5. When a developer leaves, the tokens stay valid until somebody remembers to revoke them.

The tokens are spread across machines and files. No one can list them, rotate them or see what they were used for.

Your team uses Gatana

1. A maintainer adds the GitHub server to the gateway once and grants the team access.
2. Each developer connects their AI client to the gateway, signs in and sees the GitHub tools. Optional. When the server uses per-user credentials, the developer authorizes GitHub once in Gatana.
3. The maintainer disables the destructive tools and adds a firewall rule for the rest. The change applies to every client at once.

When a developer leaves the organization, their access to every server ends with their account.

Overview of the parts

A server is made of a few parts. Each one has its own page where it needs more explanation.

Server

The server record holds the settings that apply to the server as a whole:

Transport

The transport is how Gatana reaches the server. It is fixed by the kind of server you chose when you added it: a URL and headers for a remote server, a command, image and environment for an executable app, a runtime for runnable code, a specification and base URL for OpenAPI. Servers that Gatana runs can also reserve CPU and memory, keep a persistent volume and join your Tailscale network.

Authorization and credentials

The authorization configuration describes what form the credentials have: none, API keys, OAuth 2.1 or OAuth client credentials. It also sets whether one credential is shared by the whole server or each user provides their own. The credentials themselves are stored separately and can be scoped to the server, to a user or to a profile. See Credentials.

Tools

Gatana discovers the tools of a server and caches them. The cache is refreshed automatically every couple of hours, or on demand with the Refresh button on the server page. Each cached tool keeps the name, description, input schema and annotations the server reported, plus your overrides: a tool can be disabled, renamed, given a new description or a new input schema. The client only sees the result.

Members

Access to a server is granted to users and teams. Each membership has a role:

• Member: sees and calls the tools.
• Maintainer: changes the server configuration.
• Admin: manages members and deletes the server.

Organization-wide base permissions can grant a role to everyone without a membership. See Permissions and Roles.

Files

An executable app can be given files. You upload them in Gatana, or point at a value in AWS Systems Manager or Secrets Manager, and they appear in the folder the app runs in, under the file name you choose. Use this for service account keys and other material that does not fit in an environment variable. Secrets that go into headers, environment variables or the command line come from secret stores instead.