Skip to main content

​
MCP Integration Guide

This guide covers integrating ID Wispera with Model Context Protocol (MCP) compatible AI agents.

​
Overview

The ID Wispera MCP server enables AI agents like Claude to access governed credentials through standardized MCP tools and resources.

​
Quick Setup

​
1. Install the MCP Server

npm install -g @id-wispera/mcp-server

​
2. Initialize Your Vault

idw init
idw create

​
3. Configure Your MCP Client

For Claude Desktop, add to your config: 
{
  "mcpServers": {
    "id-wispera": {
      "command": "npx",
      "args": ["@id-wispera/mcp-server"],
      "env": {
        "IDW_SESSION_TOKEN": "idw_token_..."
      }
    }
  }
}
Generate a session token with idw auth token create --label "mcp-server" --ttl 720h. The token encrypts your vault passphrase — no plaintext secrets in your configuration. For local development with OS keychain configured (idw auth login), no environment variable is needed at all — the MCP server will resolve the passphrase from your keychain.
The IDW_PASSPHRASE environment variable is also supported — set it directly or via a .env file. See the Authentication guide for the full resolution chain.

​
Available Tools

​
list_passports

List available credential passports. Input: 
{
  "status": "active",
  "platform": "openai"
}
Output: 
{
  "success": true,
  "passports": [
    {
      "id": "abc123...",
      "name": "OpenAI Production",
      "credential_type": "api-key",
      "status": "active"
    }
  ]
}

​
get_credential

Retrieve a credential value. Input: 
{
  "passport_id": "abc123...",
  "purpose": "Making API call for user request"
}
Output: 
{
  "success": true,
  "credential": "sk-...",
  "passport_name": "OpenAI Production"
}

​
request_access

Request access to a credential (for policy checking). Input: 
{
  "passport_id": "abc123...",
  "purpose": "Need to call GitHub API",
  "scope": ["repo.read"]
}
Output: 
{
  "success": true,
  "approved": true,
  "reason": "Access granted by policy"
}

​
check_policy

Check if access would be allowed without retrieving the credential. Input: 
{
  "passport_id": "abc123...",
  "action": "access"
}
Output: 
{
  "success": true,
  "allowed": true,
  "effect": "allow",
  "violations": []
}
Use check_policy to verify access before calling get_credential. This avoids unnecessary audit log entries for denied requests.

​
revoke_passport

Revoke a credential. Input: 
{
  "passport_id": "abc123...",
  "reason": "Credential may be compromised"
}

​
Available Resources

​
passport://{id}

Access passport metadata. Returns passport details without the credential value.

​
audit://{passport_id}

Access audit trail for a passport. Returns recent audit entries.

​
Security Considerations

​
Passphrase Security

  • Stored in a secure secrets manager
  • Not committed to version control
  • Rotated periodically
For production, use a secure wrapper script instead of passing the passphrase directly: 
{
  "mcpServers": {
    "id-wispera": {
      "command": "/path/to/secure-wrapper.sh",
      "args": []
    }
  }
}

​
Audit Trail

Every credential access through MCP is logged with actor, purpose, and timestamp. See the Audit log page for details.

​
Policy Enforcement

MCP requests go through the same policy evaluation as CLI access:
  • Expired and revoked passports are blocked
  • Privilege visas may require approval
  • Delegation limits are enforced
The MCP server applies identical policy rules as the CLI. There is no way to bypass policy enforcement through the MCP interface.

​
Custom MCP Server

You can build a custom MCP server on top of the ID Wispera core library: 
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { unlockVault, accessCredential } from '@id-wispera/core';

const server = new Server({
  name: 'custom-id-wispera',
  version: '1.0.0',
});

​
Troubleshooting

ProblemWhat to check
Server not startingVerify IDW_SESSION_TOKEN is set (or keychain is configured via idw auth login), vault file exists, Node.js 18+ installed
Credentials not foundCheck passport status, platform filter, and expiration date
Policy denialsReview visa type, delegation depth, expiration, and human owner requirement

​
Next steps

Framework integrations

OpenAI Agents, Google A2A, Slack, and more — governed credentials for AI frameworks.

Policy engine

Configure declarative rules that govern credential access.

Security architecture

Understand the encryption model and threat model behind ID Wispera.

Audit log

Review credential access history and compliance reporting.