> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gumstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GumstackHost

> Wrap your FastMCP server for Gumstack deployment

`GumstackHost` wraps your FastMCP server with Gumstack's infrastructure features: token validation, access control, and logging.

## Usage

```python theme={"dark"}
from mcp.server.fastmcp import FastMCP
from mcp.gumstack import GumstackHost

mcp = FastMCP("my-server")

@mcp.tool()
def my_tool() -> str:
    return "Hello"

# Wrap with GumstackHost
host = GumstackHost(mcp)
host.run()
```

## Constructor

```python theme={"dark"}
GumstackHost(server: FastMCP | Server)
```

<ParamField body="server" type="FastMCP | Server" required>
  Your MCP server instance.
</ParamField>

Automatically adds:

* **Token validation** — Verifies incoming request tokens
* **RBAC interceptor** — Checks per-tool permissions
* **Logging interceptor** — Records all tool calls

## Methods

### register\_auth

Register an OAuth provider for user authentication.

```python theme={"dark"}
host.register_auth(provider: AuthProvider) -> None
```

```python theme={"dark"}
from mcp.gumstack import AuthProvider

class MyProvider(AuthProvider):
    name = "my-provider"
    # ... implement methods

host = GumstackHost(mcp)
host.register_auth(MyProvider())
```

Multiple providers can be registered for servers that connect to multiple services.

### run

Start the server.

```python theme={"dark"}
host.run(
    host: str = "0.0.0.0",
    port: int = 8000,
    log_level: str = "info"
) -> None
```

## Environment variables

GumstackHost requires these environment variables (set automatically in production):

| Variable              | Description             |
| --------------------- | ----------------------- |
| `GUMSTACK_SERVER_ID`  | Your server's unique ID |
| `GUMSTACK_MCP_URL`    | Server's public URL     |
| `GUMLOOP_BACKEND_URL` | Gumloop API URL         |

## What it does

When a request arrives:

1. **Token validation** — Verifies the bearer token with Gumloop
2. **Context injection** — Sets `GumstackContext` with user/org info
3. **RBAC check** — Confirms user's group can access the requested tool
4. **Tool execution** — Runs your tool code
5. **Logging** — Records inputs, outputs, latency, and errors

```mermaid theme={"dark"}
flowchart TD
    REQ[Request] --> TV[Token validation]
    TV -->|Invalid| E1[401 Unauthorized]
    TV -->|Valid| CTX[Set context]
    CTX --> RBAC[Check permissions]
    RBAC -->|Denied| E2[Permission denied]
    RBAC -->|Allowed| EXEC[Execute tool]
    EXEC --> LOG[Log to analytics]
    LOG --> RESP[Response]
```