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

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. 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:

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 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 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:

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:

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:

{
  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:

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

Admin users can revoke compromised tokens:

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
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 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	createGateway, createGatewayToken, revokeGatewayToken, gatewayActivity
Adapter registry	ui/src/adapters/registry.ts	Registers available gateway adapters
OpenClaw adapter	ui/src/adapters/openclaw-gateway/index.ts	OpenClaw MCP server wrapper
Hermes adapter	ui/src/adapters/hermes-gateway/index.ts	Hermes MCP server wrapper
Onboarding helper	ui/src/lib/agent-onboarding-prompt.ts	Generates MCP server configuration payloads
Server routes	server/src/routes/tool-gateway.ts	Token validation, audit logging, request handling
URL utilities	server/src/url-utils.ts	Gateway URL parsing and authorization helpers
Governance UI	ui/src/pages/apps/gateways/gateway-helpers.ts	Token status, scope labels, admin controls
Runtime specification	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
• Token-based authentication enforces company and optional project/agent scoping via createGatewayToken in ui/src/api/tools.ts
• Server-side validation in 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 and 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.

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. 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, 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. Query parameters support time windows and result limiting for manageable audit reviews.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}