@id-wispera/mcp-server

MCP (Model Context Protocol) server for ID Wispera credential governance.

Overview

This package provides an MCP server that allows AI agents (like Claude) to securely access governed credentials through the Model Context Protocol.

Installation

npm install @id-wispera/mcp-server

Usage

Starting the Server

# Start the MCP server
npx @id-wispera/mcp-server

# With custom vault path
IDW_VAULT_PATH=~/.my-vault/vault.json npx @id-wispera/mcp-server

Configuration with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "id-wispera": {
      "command": "npx",
      "args": ["@id-wispera/mcp-server"],
      "env": {
        "IDW_VAULT_PATH": "/path/to/vault.json",
        "IDW_SESSION_TOKEN": "idw_st_..."
      }
    }
  }
}

Authentication: Generate a scoped session token with idw auth token create --name "claude-desktop" --scope read,list --ttl 7d and set it as IDW_SESSION_TOKEN. This avoids storing a plaintext passphrase in your config file.

Deprecated: IDW_PASSPHRASE is still accepted for backward compatibility but will be removed in a future release. Migrate to IDW_SESSION_TOKEN.

Available Tools

get_credential

Retrieve a credential by passport ID.

{
  "name": "get_credential",
  "arguments": {
    "passport_id": "uuid-of-passport",
    "purpose": "Making API call to OpenAI"
  }
}

list_passports

List available passports with optional filters.

{
  "name": "list_passports",
  "arguments": {
    "status": "active",
    "platform": "openai"
  }
}

request_access

Request access to a credential (creates audit entry, may require approval).

{
  "name": "request_access",
  "arguments": {
    "passport_id": "uuid-of-passport",
    "purpose": "Executing user-requested API call",
    "scope": ["chat", "completions"]
  }
}

check_policy

Check if an action is permitted by policy.

{
  "name": "check_policy",
  "arguments": {
    "passport_id": "uuid-of-passport",
    "action": "access"
  }
}

revoke_passport

Revoke a passport (requires confirmation).

{
  "name": "revoke_passport",
  "arguments": {
    "passport_id": "uuid-of-passport",
    "reason": "Credential exposed in logs"
  }
}

Available Resources

passport://{id}

Access passport metadata as a resource.

passport://a1b2c3d4-e5f6-7890-abcd-ef1234567890

audit://{passport_id}

Access audit trail for a passport.

audit://a1b2c3d4-e5f6-7890-abcd-ef1234567890

Security

• All credential access is logged to the audit trail
• Policy rules are evaluated before credential retrieval
• The server runs locally and communicates via stdio
• Credentials are never sent to external services

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | IDW_SESSION_TOKEN | Scoped session token (recommended) | | | IDW_VAULT_PATH | Path to vault file | ~/.id-wispera/vault.json | | IDW_LOG_LEVEL | Logging level | info | | IDW_PASSPHRASE | Vault passphrase | Deprecated -- use IDW_SESSION_TOKEN instead |

The server resolves authentication in order: IDW_SESSION_TOKEN > OS keychain > IDW_PASSPHRASE.

License

MIT