# Model Context Protocol (MCP) for AI Agents (Node)

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FEOPQ8h0TMi0HwSY7bbC9%2Fimage.png?alt=media&#x26;token=385e7a3b-388a-4ef4-8078-e6134f61ce7e" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To utilize AI Agent integrations with Keeper Secrets Manager (KSM), your role must have the [enforcement setting](https://docs.keeper.io/en/keeperpam/privileged-access-manager/getting-started/enforcement-policies) "Can create applications and manage secrets" enabled.
{% endhint %}

{% hint style="danger" %}
By enabling this feature, you authorize integration between Keeper and third-party AI tools or services. Keeper maintains its Zero-Trust architecture and does not access or process your vault records.

However, any data shared with third-party tools will be governed by those tools’ security, privacy, and compliance practices - not Keeper’s. You are solely responsible for configuring, managing, and auditing these integrations in accordance with your organization’s internal policies and applicable regulations.

To reduce exposure, access granted to AI Agents should be limited to only the minimum necessary folders in the Keeper Vault required to accomplish your specific use case.
{% endhint %}

## AI Agent Integration with Model Context Protocol (MCP)

Keeper Secrets Manager works with AI agents through the Model Context Protocol (MCP), enabling AI Agents to securely interact with specific vault folders. This integration provides a zero-trust architecture where AI agents are explicitly allowed to access designated information from the Keeper Vault.

The Model Context Protocol integration acts as a secure bridge between AI assistants and Keeper Secrets Manager. It allows AI tools to help you manage secrets while maintaining the highest security standards through human-in-the-loop confirmations for sensitive operations.

**GitHub**: <https://github.com/Keeper-Security/keeper-mcp-node>

### Key Benefits

**Zero Trust Architecture**: AI agents are assigned specific folders in the vault\
**Human-in-the-Loop**: Confirmation prompts for sensitive operations\
**Enterprise Ready**: Comprehensive audit logging and compliance features\
**Multi-Platform**: Works on Linux, macOS, and Windows

### What Can AI Assistants Do?

With KSM MCP integration, AI assistants can help you:

#### Secret Operations

**List secrets** - Browse your accessible secrets\
**Search secrets** - Find secrets by title, URL, username, or other fields\
**Retrieve secrets** - Get specific secret values (with confirmation for unmasked data)\
**Create secrets** - Generate new secret entries\
**Update secrets** - Modify existing secret information\
**Delete secrets** - Remove secrets (with confirmation)

#### File Management

**List attachments** - View file attachments on secrets\
**Upload files** - Add file attachments to secrets\
**Download files** - Retrieve file attachments\
**Delete files** - Remove file attachments

#### Utilities

**Generate passwords** - Create secure passwords with customizable parameters\
**Get TOTP codes** - Retrieve current time-based one-time passwords\
**Execute KSM notation queries** - Use Keeper's notation system for complex operations\
**Health checks** - Monitor server status and connectivity

### Setup and Installation

#### (1) Create Secrets Manager Application

From Keeper Secrets Manager, create an Application or use an existing application.

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2F8QSyaSvPjGJIkLSGzBcK%2FScreenshot%202025-05-26%20at%202.34.17%E2%80%AFPM.png?alt=media&#x26;token=814e9b6c-5a46-4ba8-9249-78b3ef6281d1" alt=""><figcaption><p>Create an Application and assign folders</p></figcaption></figure>

#### (2) Create a Device Token

Discard the first Device token, and click on "Add Device" to generate a new Base64 configuration that will be provided to your AI agent.

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2F3QRzGtTGmBpTJSt6ULp7%2FScreenshot%202025-05-26%20at%202.35.15%E2%80%AFPM.png?alt=media&#x26;token=d4a936d8-2caa-4f85-8f38-9c13a43a5389" alt=""><figcaption><p>Generate Base64 Token</p></figcaption></figure>

#### (3) Configure the MCP Server

You have two options for providing your Keeper configuration:

#### **Option A: Configuration File (Recommended)**

Place your downloaded configuration file in one of these locations:

* `~/.keeper/ksm-config.json` (recommended)
* `./ksm-config.json` (in the current directory)

#### **Option B: One-Time Token**

If you have a one-time token instead:

```
export KSM_TOKEN="US:YOUR_ONE_TIME_TOKEN_HERE"
```

The server will use this token to generate and save a configuration file automatically.

#### (4) Test the Server

Run the server directly to test:

```bash
npm start
```

You should see: `Keeper MCP server is running`

### Usage with MCP Clients

#### Claude Desktop

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

```json
{
  "mcpServers": {
    "keeper": {
      "command": "node",
      "args": ["/path/to/keeper-mcp-node/dist/index.js"]
    }
  }
}
```

#### Postman

1. In Postman, go to the API Network tab
2. Create or select an MCP request
3. Configure the stdio connection:
   * Command: `node`
   * Arguments: `/path/to/keeper-mcp-node/dist/index.js`

#### Other MCP Clients

The server communicates via stdio, so you can integrate it with any MCP-compatible client by running:

```bash
node /path/to/keeper-mcp-node/dist/index.js
```

### Available Tools

#### Secret Operations

**`ksm_list_secrets`**

#### List all secrets accessible to your application (metadata only)

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_list_secrets",
    "arguments": {}
  }
}
```

Response:

```typescript
[
  {
    "uid": "XXXXXXXXXXXXXXXXXXXXXX",
    "title": "My Secret",
    "type": "login"
  }
]
```

**`ksm_get_secret`**

#### Retrieve a complete secret by UID or title (sensitive fields masked by default)

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_get_secret",
    "arguments": {
      "identifier": "My Secret",
      "unmask": false
    }
  }
}
```

**`ksm_search_secrets`**

#### Search for secrets by title, notes, or other field content

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_search_secrets",
    "arguments": {
      "query": "database"
    }
  }
}
```

**`ksm_create_secret`**

#### Create a new secret in Keeper Secrets Manager (requires confirmation)

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_create_secret",
    "arguments": {
      "title": "New Database Credentials",
      "type": "login",
      "fields": {
        "login": "admin",
        "password": "secure_password",
        "url": "https://db.example.com"
      },
      "notes": "Production database",
      "folderId": "FOLDER_UID"
    }
  }
}
```

**`ksm_update_secret`**

#### Update an existing secret (requires confirmation)

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_update_secret",
    "arguments": {
      "identifier": "My Secret",
      "updates": {
        "title": "Updated Title",
        "fields": {
          "password": "new_password"
        }
      }
    }
  }
}
```

**`ksm_delete_secret`**

#### Delete a secret from Keeper Secrets Manager (requires confirmation)

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_delete_secret",
    "arguments": {
      "identifier": "My Secret"
    }
  }
}
```

**`ksm_get_field`**

#### Get a specific field value from a secret

**Request:**

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_get_field",
    "arguments": {
      "identifier": "My Secret",
      "field": "password"
    }
  }
}
```

Common field names:

* `password` - The password field
* `login` - Username/email
* `url` - Website URL
* Custom field labels

#### Folder Operations

**`ksm_list_folders`**

#### List all accessible folders in Keeper Secrets Manager

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_list_folders",
    "arguments": {}
  }
}
```

**`ksm_create_folder`**

#### Create a new folder (requires confirmation; must specify a parent shared folder)

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_create_folder",
    "arguments": {
      "name": "Development Secrets",
      "parentFolderId": "PARENT_FOLDER_UID"
    }
  }
}
```

**`ksm_delete_folder`**

#### Delete a folder (requires confirmation)

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_delete_folder",
    "arguments": {
      "folderId": "FOLDER_UID",
      "force": false
    }
  }
}
```

#### File Management

**`ksm_upload_file`**

#### Upload a file attachment to a secret (requires confirmation)

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_upload_file",
    "arguments": {
      "identifier": "My Secret",
      "filePath": "/path/to/certificate.pem",
      "fileName": "server-cert.pem"
    }
  }
}
```

**`ksm_download_file`**

#### Download a file attachment from a secret

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_download_file",
    "arguments": {
      "identifier": "My Secret",
      "fileId": "certificate.pem",
      "outputPath": "/tmp/downloaded-cert.pem"
    }
  }
}
```

#### Utilities

**`ksm_generate_password`**

#### Generate a secure password

Can optionally save to a new secret without exposing it to the AI

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_generate_password",
    "arguments": {
      "length": 24,
      "includeUppercase": true,
      "includeLowercase": true,
      "includeNumbers": true,
      "includeSpecial": true,
      "saveToSecret": {
        "title": "Generated API Key",
        "login": "api-user",
        "url": "https://api.example.com",
        "notes": "Auto-generated API key"
      }
    }
  }
}
```

**`ksm_get_totp_code`**

#### Get the current TOTP code for a secret that has TOTP configured

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_get_totp_code",
    "arguments": {
      "identifier": "My 2FA Secret"
    }
  }
}
```

**`ksm_get_server_version`**

#### Get the current version of the KSM MCP server

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_get_server_version",
    "arguments": {}
  }
}
```

**`ksm_health_check`**

#### Check the operational status of the MCP server and its connection to KSM

Request:

```typescript
{
  "method": "tools/call",
  "params": {
    "name": "ksm_health_check",
    "arguments": {}
  }
}
```

### Troubleshooting

#### Error: No Keeper Secrets Manager configuration found

* Ensure your configuration file is in one of the supported locations
* Check that the file has proper JSON formatting
* Verify file permissions (should be readable by your user)

#### Error: Failed to initialize KSM

* Verify your configuration file contains all required fields
* Check that your application has access to the shared folders/secrets
* Ensure your device hasn't been revoked in Keeper

#### Connection Issues

* Verify you have internet connectivity
* Check if your organization has IP restrictions enabled
* Ensure your Keeper subscription includes Secrets Manager

***

For additional setup details, see: <https://github.com/Keeper-Security/keeper-mcp-node/>