npm package: @id-wispera/mcp-server
Description: MCP server for ID Wispera credential governance
Author: Wispera AI Inc.
Latest version: 0.1.0

# @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

```bash
npm install @id-wispera/mcp-server
```

## Usage

### Starting the Server

```bash
# 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`):

```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.

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

### list_passports

List available passports with optional filters.

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

### request_access

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

```json
{
  "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.

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

### revoke_passport

Revoke a passport (requires confirmation).

```json
{
  "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