Secure an MCP server

// Stands in for your product's ticket table.
const tenantId = process.env.ACME_TENANT_ID;
export const tickets = new Map([
  ['T-1', { id: 'T-1', tenantId, title: 'Cannot export invoices', status: 'open' }],
  ['T-2', { id: 'T-2', tenantId, title: 'Typo on the pricing page', status: 'open' }],
]);

import { IamError } from 'better-iam';
import { sqliteAdapter } from 'better-iam/adapter-sqlite';
import { findDocument } from './documents.mjs'; // your document lookup from the Quickstart
import { tickets } from './tickets.mjs';

const ticketActions = ['tickets:read', 'tickets:update', 'tickets:delete'];

export default {
  database: sqliteAdapter({ filename: './iam.db' }),
  secret: process.env.BETTER_IAM_SECRET,
  baseURL: process.env.BETTER_IAM_BASE_URL,
  authentication: {
    sendEmail: async (message) => {
      console.log(message.template, message.to, message.payload); // development only
    },
  },
  permissions: {
    resourceTypes: {
      document: { actions: ['documents:read', 'documents:write'], attributes: { ownerId: 'string' } },
      ticket: { description: 'A support ticket', actions: ticketActions },
      'ticket-queue': { description: "An organization's ticket queue", actions: ticketActions },
    },
  },
  resolveResource: async ({ type, id }) => {
    if (type === 'ticket-queue') {
      // A queue's ID is the ID of the organization that owns it.
      return { type, id, tenantId: id };
    }
    if (type === 'ticket') {
      const ticket = tickets.get(id);
      if (!ticket) throw new IamError('NOT_FOUND', 'Ticket not found', 404);
      return { type, id, tenantId: ticket.tenantId };
    }
    if (type === 'document') {
      const document = await findDocument(id);
      return { type, id, tenantId: document.tenantId, attributes: { ownerId: document.ownerId } };
    }
    throw new IamError('NOT_FOUND', 'Unknown resource type', 404);
  },
};

import { iam } from '../iam';

const tenantId = process.env.ACME_TENANT_ID!;
const signIn = await iam.api.auth.signIn({
  tenantId,
  email: process.env.ACME_OWNER_EMAIL!,
  password: process.env.ACME_OWNER_PASSWORD!,
});
if ('mfaRequired' in signIn) throw new Error('This owner needs MFA');
const owner = { token: signIn.token };

const reader = await iam.api.roles.create(owner, {
  tenantId,
  name: 'Ticket reader',
  permissions: ['tickets:read'],
});
await iam.api.roles.create(owner, {
  tenantId,
  name: 'Support',
  permissions: ['tickets:read', 'tickets:update'],
});

const digest = await iam.api.serviceAccounts.create(owner, { tenantId, name: 'Ticket digest' });
await iam.api.bindings.create(owner, {
  tenantId,
  roleId: reader.id,
  subjectType: 'identity',
  subjectId: digest.id,
});
const { token: readerKey } = await iam.api.credentials.create(owner, {
  tenantId,
  identityId: digest.id,
  name: 'mcp-test',
});

console.log({ ownerToken: signIn.token, readerKey }); // test credentials for the next steps

npx tsx scripts/setup-mcp.ts
export OWNER_TOKEN=…   # ownerToken from the output
export READER_KEY=…    # readerKey from the output (a biam_key_… token)

import type { McpCaller } from 'better-iam/mcp';
import { tickets } from '../tickets.mjs';

export const tools = [
  {
    name: 'search_tickets',
    description: 'List open support tickets of the organization',
    inputSchema: { type: 'object', properties: { query: { type: 'string' } } },
  },
  {
    name: 'close_ticket',
    description: 'Close a support ticket',
    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
  },
  {
    name: 'delete_ticket',
    description: 'Permanently delete a support ticket',
    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
  },
  {
    name: 'ping',
    description: 'Check that the server is reachable',
    inputSchema: { type: 'object', properties: {} },
  },
];

type JsonRpcRequest = {
  jsonrpc: '2.0';
  id?: string | number | null;
  method: string;
  params?: Record<string, unknown>;
};

const result = (id: JsonRpcRequest['id'], value: unknown) =>
  Response.json({ jsonrpc: '2.0', id, result: value });
const text = (id: JsonRpcRequest['id'], value: string, isError = false) =>
  result(id, { content: [{ type: 'text', text: value }], isError });

export async function handleMcp(request: Request, caller: McpCaller): Promise<Response> {
  if (request.method !== 'POST') return new Response(null, { status: 405, headers: { allow: 'POST' } });
  const message = (await request.json()) as JsonRpcRequest;
  if (message.id === undefined) return new Response(null, { status: 202 }); // notifications

  const who = caller.kind === 'iam' ? caller.identityId : (caller.subject ?? caller.clientId);
  switch (message.method) {
    case 'initialize':
      return result(message.id, {
        // This demo accepts the client's protocol version; a production server negotiates it.
        protocolVersion: String(message.params?.protocolVersion ?? '2025-06-18'),
        capabilities: { tools: {} },
        serverInfo: { name: 'acme-tickets', version: '1.0.0' },
      });
    case 'ping':
      return result(message.id, {});
    case 'tools/list':
      return result(message.id, { tools });
    case 'tools/call': {
      const name = String(message.params?.name);
      const args = (message.params?.arguments ?? {}) as Record<string, unknown>;
      if (name === 'ping') return text(message.id, 'pong');
      if (name === 'search_tickets')
        return text(message.id, JSON.stringify([...tickets.values()].filter((t) => t.status === 'open')));
      const ticket = tickets.get(String(args.id));
      if (!ticket) return text(message.id, `No ticket ${String(args.id)}`, true);
      if (name === 'close_ticket') {
        ticket.status = 'closed';
        return text(message.id, `Closed ${ticket.id} for ${who}`);
      }
      if (name === 'delete_ticket') {
        tickets.delete(ticket.id);
        return text(message.id, `Deleted ${ticket.id} for ${who}`);
      }
      return text(message.id, `Unknown tool: ${name}`, true);
    }
    default:
      return Response.json({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'Method not found' } });
  }
}

import type { McpToolRule } from 'better-iam/mcp';

const tenantId = process.env.ACME_TENANT_ID!;
const queue = { type: 'ticket-queue', id: tenantId };
const ticketFrom = (args: Record<string, unknown>) => ({ type: 'ticket', id: String(args.id) });

export const toolRules: Record<string, McpToolRule> = {
  search_tickets: { action: 'tickets:read', resource: queue, scopes: ['tickets:read'] },
  close_ticket: { action: 'tickets:update', resource: ticketFrom, listAs: queue, scopes: ['tickets:write'] },
  delete_ticket: { action: 'tickets:delete', resource: ticketFrom, listAs: queue, scopes: ['tickets:write'] },
  ping: { public: true },
};

import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { createMcpGate } from 'better-iam/mcp';
import { iam } from '../iam';
import { handleMcp } from './handler';
import { toolRules } from './rules';

const gate = createMcpGate({
  iam,
  tenantId: process.env.ACME_TENANT_ID!, // decisions are made in the organization that runs this server
  tools: toolRules,
  unlisted: 'deny', // a tool without a rule is hidden and refused (the default)
});

const app = new Hono();
app.all('/mcp', (c) => gate(c.req.raw, handleMcp));
serve({ fetch: app.fetch, port: 4100 });

npx tsx mcp/server.ts

mcp() { curl -s http://localhost:4100/mcp -H "authorization: Bearer $1" \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "$2"; echo; }

# The read-only service account sees only what it may use:
mcp "$READER_KEY" '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# {"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"search_tickets",…},{"name":"ping",…}]}}

# Calling a hidden tool anyway is refused as a tool error the model can read:
mcp "$READER_KEY" '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"close_ticket","arguments":{"id":"T-1"}}}'
# {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"Access denied: you may not call close_ticket"}],"isError":true}}

# The owner may use every tool:
mcp "$OWNER_TOKEN" '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"close_ticket","arguments":{"id":"T-1"}}}'
# {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Closed T-1 for …"}],"isError":false}}

import { readFileSync } from 'node:fs';
import { createOAuthProvider } from 'better-iam/oauth';
import { iam } from './iam';

const keys = JSON.parse(readFileSync(process.env.OAUTH_KEY_FILE!, 'utf8'));
export const origin = 'http://localhost:3000';
export const invoicesApi = 'http://localhost:4000/api';
export const ticketsMcp = 'http://localhost:4100/mcp';

export const issuer = createOAuthProvider({
  ...iam.protocolHost,
  issuer: `${origin}/oauth`,
  jwks: keys.jwks,
  cookieKeys: keys.cookieKeys,
  encryptionKey: keys.encryptionKey,
  trustedOrigins: [origin],
  allowInsecureLocalhost: true, // development only
  resourceServers: {
    [invoicesApi]: { scopes: ['invoices:read', 'invoices:write'], accessTokenTtl: 600 },
    [ticketsMcp]: { scopes: ['tickets:read', 'tickets:write'] }, // added
  },
  // Added: MCP hosts register themselves without a token. Every registration joins Acme, may ask for
  // at most these scopes, and may only get tokens for the MCP server.
  registration: {
    anonymous: () => ({
      tenantId: process.env.ACME_TENANT_ID!,
      scopes: ['openid', 'offline_access', 'tickets:read', 'tickets:write'],
      resources: [ticketsMcp],
      maxClients: 100,
    }),
  },
  interactionUrl: (uid) => `${origin}/interactions/${encodeURIComponent(uid)}`,
  renderDevicePage: ({ form }) => `<!doctype html><title>Device sign-in</title>${form}`,
  renderLogoutPage: ({ form }) => `<!doctype html><title>Sign out</title>${form}`,
});

import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { createMcpGate } from 'better-iam/mcp';
import { createAccessTokenVerifier } from 'better-iam/oauth';
import { iam } from '../iam';
import { handleMcp } from './handler';
import { toolRules } from './rules';

const resource = 'http://localhost:4100/mcp';
const authorizationServer = 'http://localhost:3000/oauth';

const gate = createMcpGate({
  iam,
  tenantId: process.env.ACME_TENANT_ID!,
  tools: toolRules,
  oauth: createAccessTokenVerifier({ issuer: authorizationServer, audience: resource }),
  metadata: {
    resource,
    authorizationServers: [authorizationServer],
    scopes: ['tickets:read', 'tickets:write'],
    resourceName: 'Acme tickets',
  },
});

const app = new Hono();
app.all('/mcp', (c) => gate(c.req.raw, handleMcp));
// The gate serves the metadata document itself; route its well-known path to the gate too.
app.all('/.well-known/oauth-protected-resource/mcp', (c) => gate(c.req.raw, handleMcp));
serve({ fetch: app.fetch, port: 4100 });

curl -s http://localhost:4100/.well-known/oauth-protected-resource/mcp
# {"resource":"http://localhost:4100/mcp","authorization_servers":["http://localhost:3000/oauth"],
#  "scopes_supported":["tickets:read","tickets:write"],"bearer_methods_supported":["header"],"resource_name":"Acme tickets"}

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "The person you act for must confirm this call first. A confirmation request was sent to them (it expires at 2026-11-07T10:30:00.000Z). Call delete_ticket again once they approve it."
      }
    ],
    "isError": true,
    "_meta": {
      "better-iam/confirmationId": "…",
      "better-iam/confirmationExpiresAt": 1794047400000
    }
  }
}

confirmationReason: (tool, args) => `Your assistant wants to run ${tool} on ticket ${String(args.id)}.`,

import { createMcpAuthorizer, type McpCaller } from 'better-iam/mcp';
import { iam } from '../iam';
import { toolRules } from './rules';

export const authorizer = createMcpAuthorizer({
  iam,
  tenantId: process.env.ACME_TENANT_ID!,
  tools: toolRules,
});

// In your HTTP layer: undefined means no valid credential, so answer 401.
export const callerOf = (request: Request): Promise<McpCaller | undefined> => authorizer.authenticate(request);

// In your tools/call handler:
export async function assertCanCall(caller: McpCaller, name: string, args: Record<string, unknown>) {
  const decision = await authorizer.canCall(caller, name, args);
  // decision.reason: ALLOWED, PUBLIC, ACCESS_DENIED, UNKNOWN_TOOL, NO_RULE_FOR_CALLER,
  // INSUFFICIENT_SCOPE, or CONFIRMATION_REQUESTED (with decision.confirmation.id and expiresAt)
  if (!decision.allowed) throw new Error(`Refused: ${decision.reason}`);
}

// In your tools/list handler:
export const listFor = <T extends { name: string }>(caller: McpCaller, tools: T[]) =>
  authorizer.visibleTools(caller, tools);