MCP server object capabilities security — capability-based authorization for MCP tool access, unforgeable capability references, and capability attenuation

Ambient authority vs. object capabilities in MCP tool dispatch

Implementing object capabilities in a Node.js MCP server

Object capabilities in JavaScript are simply closures that encapsulate state and expose only the operations they should permit. The key discipline: the capability object is the only reference to the underlying resource — it is never exposed globally or through module exports accessible to untrusted code.

// Bad pattern: ambient authority — any module can import and call these
import { db } from './database.js';
import { emailClient } from './email.js';

export function handleToolCall(name, args) {
  if (name === 'queryUsers') return db.query('SELECT * FROM users WHERE id = ?', [args.userId]);
  if (name === 'sendAlert') return emailClient.send({ to: args.to, body: args.body });
}

// Good pattern: capability-based — tools only receive the capabilities they need
function createQueryCapability(db, allowedTable) {
  return {
    query: (userId) => db.query(
      `SELECT * FROM ${allowedTable} WHERE id = ? AND deleted_at IS NULL`,
      [userId]
    ),
    // No insert, update, delete — not in this capability
  };
}

function createEmailCapability(emailClient, allowedDomain) {
  return {
    send: (to, subject, body) => {
      if (!to.endsWith(`@${allowedDomain}`)) throw new Error('CAP_EMAIL_DOMAIN_VIOLATION');
      return emailClient.send({ to, subject, body });
    },
  };
}

// At startup: construct capabilities with their constraints baked in
const userQueryCap = createQueryCapability(db, 'users');
const internalEmailCap = createEmailCapability(emailClient, 'internal.example.com');

// Tool handler only receives the capabilities it is explicitly passed
function createToolHandler({ queryCap, emailCap }) {
  return function handleToolCall(name, args) {
    if (name === 'queryUser')  return queryCap.query(args.userId);
    if (name === 'sendAlert')  return emailCap.send(args.to, args.subject, args.body);
    throw new Error('UNKNOWN_TOOL');
  };
}

const toolHandler = createToolHandler({
  queryCap: userQueryCap,
  emailCap: internalEmailCap,
});
// toolHandler has no direct access to db or emailClient — only the attenuated capabilities

Capability attenuation via membrane objects

A membrane is a capability wrapper that interposes on all operations, applying additional constraints before delegating to the underlying capability. In MCP servers, membranes are useful for tenant isolation: each tenant session receives a membrane over the base capability that constrains all operations to that tenant's data.

function createTenantMembrane(baseCap, tenantId) {
  return {
    query: (userId) => {
      // Attenuate: enforce tenant scope on every call
      return baseCap.queryWithTenant(userId, tenantId);
    },
    // Operations not in the membrane interface are structurally inaccessible
    // baseCap.adminQuery() cannot be reached through the membrane
  };
}

// Session setup: each session gets a membrane scoped to its tenant
function onSessionStart(tenantId, baseCap) {
  const sessionCap = createTenantMembrane(baseCap, tenantId);
  // Pass sessionCap to the tool handler; it cannot exceed tenant scope
  return createToolHandler({ queryCap: sessionCap, emailCap: internalEmailCap });
}

Revocable capabilities for session invalidation

function createRevocableCapability(target) {
  let alive = true;

  const proxy = new Proxy(target, {
    get(obj, prop) {
      if (!alive) throw new Error('CAP_REVOKED');
      return obj[prop];
    },
    apply(obj, thisArg, args) {
      if (!alive) throw new Error('CAP_REVOKED');
      return obj.apply(thisArg, args);
    },
  });

  const revoke = () => { alive = false; };

  return { cap: proxy, revoke };
}

// On session logout or token expiry:
const { cap: sessionCap, revoke: revokeSession } = createRevocableCapability(baseCap);
// Pass sessionCap to tool handler
// On logout:
revokeSession(); // All future calls through sessionCap throw immediately

SkillAudit findings for object capability violations in MCP servers

SkillAudit's static analysis identifies ambient authority patterns — global imports used directly in tool handlers without attenuation. Run a free audit to check your MCP server's authorization architecture.