Identities
The on-behalf-of directory and plugging in your own user store via resolvers.
An MCP session binds to an agent key (from Authorization) and an on-behalf-of identity (from
X-Weavekit-On-Behalf-Of). The on-behalf-of ref must resolve to a subject; RBAC then decides that
subject's tool surface.
mcp.identities is the static directory (ref → IdentitySubject). A session's proxied user must
resolve here; a missing or unknown ref is rejected at session establishment. When unset, the engine
resolves on-behalf-of refs through its own identity directory (weavekit_user — see
Identity).
Plugging in your own user store
Both auth.source and mcp.identities accept either a static map (the defaults) or a
resolver function, so you can drive authentication and on-behalf-of identity from your own
directory.
auth.source—Record<string, IdentitySubject> | AuthResolver, whereAuthResolver = (header) => subject | null | Promise<...>. The resolver receives the fullAuthorizationheader (including theBearerprefix) and may verify a JWT or look up the user asynchronously. Returnnullfor unauthenticated (401). When anidentity.verifieris configured,auth.sourcemay be omitted (the verifier + engine directory authenticate instead).mcp.identities—Record<string, IdentitySubject> | IdentityResolver, whereIdentityResolver = (ref) => subject | null | Promise<...>. The resolver may query your user table and return the subject with its roles and department. Returnnullfor an unknown ref (the session is rejected with 400).
// weavekit.config.ts — auth + identities driven by the customer's user table
export default {
schemaDir: '.',
auth: {
source: async (header) => {
const token = header?.replace(/^Bearer\s+/i, ''); // verify your JWT here
return token === undefined ? null : { id: `agent-${token}`, roles: ['agent'] };
},
},
adapters: {
mcp: {
identities: async (ref) => { // query the customer's user table
const row = await pool.query(
`SELECT id, role, dept_id FROM crm_users WHERE id = $1`, [ref]);
if (row.rows.length === 0) return null;
const { id, role, dept_id } = row.rows[0];
return { id, roles: [role], ...(dept_id ? { departmentId: dept_id } : {}) };
},
},
},
} satisfies EngineConfig;A resolver wins over the static map when both are provided for the same field. Either way, the tool surface is compiled per identity and RBAC is re-enforced at call time — the double layer never changes.
For a database-backed directory, prefer the engine's own identity sync over hand-writing a resolver — see Identity. For the runnable case (a customer user table + a JWT auth source), see the user-store practice.
Impersonation
A call-level onBehalfOf tool argument lets an agent switch identity per call — disabled by
default (mcp.impersonation defaults to off). Set it to 'directory' to allow switching to any
identity in the configured directory. The identity bound at handshake (X-Weavekit-On-Behalf-Of) is
always enforced.
Related
- MCP overview
- Tool surface
- Identity — the engine directory and sync
- RBAC