# How to Integrate MCP Servers with the Paperclip Tool Gateway and Access Governance

> Securely integrate MCP servers with Paperclip's Tool Gateway. Enforce access controls, use token authentication, and leverage audit logging for robust access governance.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: how-to-guide
- Published: 2026-08-18

---

**Paperclip's Tool Gateway uses adapter-based implementations, token-scoped authentication, and comprehensive audit logging to securely connect external MCP servers like OpenClaw and Hermes while enforcing company-level access controls.**

The **Tool Gateway** in Paperclip serves as the integration point between external MCP (Multi-Channel Protocol) servers and Paperclip's agent runtime. This article explains how to register MCP servers, issue scoped tokens, and enforce governance policies using the actual source code implementation from the `paperclipai/paperclip` repository.

## Adapter-Based Gateway Architecture

Paperclip supports MCP server integration through **UI adapters** that abstract protocol differences. Each adapter handles server startup, stdout parsing, and RPC translation into Paperclip's tool-runtime API.

Available adapters include:

- **`openclaw_gateway`** – wraps the OpenClaw MCP server
- **`hermes_gateway`** – wraps the Hermes MCP server

Adapters are implemented under `ui/src/adapters/` and registered in [`ui/src/adapters/registry.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/adapters/registry.ts). The registry exposes adapter metadata to the UI for gateway creation flows.

When you create a gateway, you select an adapter type that determines how Paperclip communicates with your MCP server. The adapter also defines what configuration payload the MCP server needs to authenticate back to Paperclip.

## Token-Based Authentication and Scoping

Every gateway uses **one-time-use gateway tokens** for authentication. These tokens carry security context that enforces access boundaries.

Token properties include:

- **TTL** – time-to-live in seconds (configurable per token)
- **Company scope** – binds token to a specific Paperclip company
- **Optional context scopes** – restricts token to a project (`contextScopeType: 'project'`) or agent

Token creation happens through `createGatewayToken` in [`ui/src/api/tools.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/api/tools.ts):

```typescript
import { api } from '@/api';

const token = await api.createGatewayToken(companyId, gateway.id, {
  ttlSeconds: 86_400,           // 24 hours
  contextScopeType: 'project',  // optional restriction
  contextScopeId: 'proj-123',
});

```

MCP servers must present tokens in the `Authorization: Bearer <token>` header for all tool requests. The server-side routes under [`server/src/routes/tool-gateway.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/tool-gateway.ts) validate tokens and enforce company-scoped authorization using the same checks as other Paperclip APIs.

## Step-by-Step MCP Server Integration

### 1. Register the MCP Server via Adapter Selection

Use the onboarding helper in [`ui/src/lib/agent-onboarding-prompt.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/lib/agent-onboarding-prompt.ts) to generate the adapter configuration payload. This helper constructs the JSON needed for your selected adapter type.

### 2. Create the Gateway

Call `createGateway` from [`ui/src/api/tools.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/api/tools.ts):

```typescript
const gateway = await api.createGateway(companyId, {
  type: 'hermes_gateway',
  name: 'Production Hermes Bridge',
  defaultProfileMode: 'gateway_only',
});

```

This creates a `ToolMcpGateway` record and returns the gateway's public IDs.

### 3. Issue and Distribute the Token

Generate a token with appropriate scope restrictions, then provide it to your MCP server configuration.

### 4. Configure the MCP Server

For **Hermes**, set environment variables and run:

```bash
export API_SERVER_ENABLED=true
export API_SERVER_KEY=$(openssl rand -hex 32)
hermes gateway run --replace --accept-hooks

```

The Paperclip UI generates the connection payload shown to users:

```typescript
{
  adapterType: 'hermes_gateway',
  agentDefaultsPayload: {
    apiBaseUrl: 'http://127.0.0.1:8642',
    apiKey: '<API_SERVER_KEY>',
    paperclipApiUrl: 'http://localhost:3100/api',
  },
  headers: { 'x-openclaw-token': '<gateway-token>' }
}

```

For **OpenClaw**, the token passes via the `x-openclaw-token` header as specified in your gateway configuration.

### 5. Validate Token Enforcement

All inbound requests hit the `/tool-gateway/*` routes where:

- Token hash is validated against stored records
- Company membership is verified
- Context scope restrictions are applied
- Policy limits (e.g., concurrent token quotas) are checked

### 6. Monitor and Audit Activity

Query the activity log via `gatewayActivity` in [`ui/src/api/tools.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/api/tools.ts):

```typescript
const logs = await api.gatewayActivity({
  companyId,
  window: '30d',
  limit: 50,
});

```

Admin users can revoke compromised tokens:

```typescript
await api.revokeGatewayToken(companyId, token.id);

```

## Governance and Auditing

Every gateway action is recorded in the `activity_log` table. The audit trail captures:

- Gateway creation and deletion
- Token issuance and revocation
- Tool execution requests and responses

Governance rules are enforced at multiple layers:

| Layer | Enforcement Point | Source File |
|-------|-------------------|-------------|
| Role checks | Route handlers verify admin status for gateway enable/disable | [`server/src/routes/tool-gateway.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/tool-gateway.ts) |
| Token quotas | Per-project or per-company limits on active tokens | Route handlers inspecting `contextScope*` fields |
| Scope validation | Tokens restricted to specific projects/agents cannot access broader resources | Token validation middleware |

The UI helper functions in [`ui/src/pages/apps/gateways/gateway-helpers.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/pages/apps/gateways/gateway-helpers.ts) calculate token status, render scope labels, and present governance controls to administrators.

## Key Source Files Reference

| Component | Path | Purpose |
|-----------|------|---------|
| Gateway API client | [`ui/src/api/tools.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/api/tools.ts) | `createGateway`, `createGatewayToken`, `revokeGatewayToken`, `gatewayActivity` |
| Adapter registry | [`ui/src/adapters/registry.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/adapters/registry.ts) | Registers available gateway adapters |
| OpenClaw adapter | [`ui/src/adapters/openclaw-gateway/index.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/adapters/openclaw-gateway/index.ts) | OpenClaw MCP server wrapper |
| Hermes adapter | [`ui/src/adapters/hermes-gateway/index.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/adapters/hermes-gateway/index.ts) | Hermes MCP server wrapper |
| Onboarding helper | [`ui/src/lib/agent-onboarding-prompt.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/lib/agent-onboarding-prompt.ts) | Generates MCP server configuration payloads |
| Server routes | [`server/src/routes/tool-gateway.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/tool-gateway.ts) | Token validation, audit logging, request handling |
| URL utilities | [`server/src/url-utils.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/url-utils.ts) | Gateway URL parsing and authorization helpers |
| Governance UI | [`ui/src/pages/apps/gateways/gateway-helpers.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/pages/apps/gateways/gateway-helpers.ts) | Token status, scope labels, admin controls |
| Runtime specification | [`doc/spec/agents-runtime.md`](https://github.com/paperclipai/paperclip/blob/main/doc/spec/agents-runtime.md) | Gateway message contracts and token payload schemas |

## Summary

- **Paperclip integrates MCP servers through adapter-based gateways** located in `ui/src/adapters/` with registration in [`registry.ts`](https://github.com/paperclipai/paperclip/blob/main/registry.ts)
- **Token-based authentication** enforces company and optional project/agent scoping via `createGatewayToken` in [`ui/src/api/tools.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/api/tools.ts)
- **Server-side validation** in [`server/src/routes/tool-gateway.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/tool-gateway.ts) ensures all requests meet governance policies
- **Complete audit logging** enables monitoring through `gatewayActivity` and administrative revocation through `revokeGatewayToken`
- **Governance controls** restrict gateway management to admins and enforce token quotas based on scope

## Frequently Asked Questions

### What MCP servers are compatible with Paperclip's Tool Gateway?

Paperclip provides official adapters for **OpenClaw** and **Hermes** in [`ui/src/adapters/openclaw-gateway/index.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/adapters/openclaw-gateway/index.ts) and [`ui/src/adapters/hermes-gateway/index.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/adapters/hermes-gateway/index.ts). Any MCP server can integrate by implementing the protocol expected by these adapters or by creating a custom adapter registered in [`ui/src/adapters/registry.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/adapters/registry.ts).

### How do gateway tokens prevent unauthorized cross-company access?

Each token embeds a **company scope** enforced by server-side validation in [`server/src/routes/tool-gateway.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/tool-gateway.ts). The route handlers verify that the authenticated company matches the token's company claim before processing any tool request. Optional `contextScopeType` and `contextScopeId` fields further restrict access to specific projects or agents.

### Can tokens be revoked before their TTL expires?

Yes. Administrators call `api.revokeGatewayToken(companyId, token.id)` from [`ui/src/api/tools.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/api/tools.ts), which immediately invalidates the token regardless of remaining TTL. Revocation events are logged to the `activity_log` table for audit purposes.

### Where is the gateway activity audit data stored?

All gateway actions are recorded in the `activity_log` table. The UI retrieves these records via `GET /tool-gateway/audit`, exposed through the `gatewayActivity` function in [`ui/src/api/tools.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/api/tools.ts). Query parameters support time windows and result limiting for manageable audit reviews.