npm package: @keyid/agent-kit
Description: KeyID MCP server for agent email, SMS, OTP/TOTP, and signup verification
Latest version: 0.4.0

<!-- mcp-name: io.github.KeyID-AI/keyid -->
# @keyid/agent-kit

KeyID MCP for signup sessions, browser continuity, agent email, SMS, OTP/TOTP, persona state, and durable secrets.

Remote-first endpoint: `https://keyid.ai/mcp`

Local stdio fallback: `npx -y @keyid/agent-kit`

## Why this package

- Hosted remote MCP for OAuth-ready Claude and Cursor connectors
- Local stdio mode when you want to keep the Ed25519 keypair under your control
- Workflow-first tools instead of a raw CRUD-heavy surface
- Generated registry metadata, Smithery config, docs, and example assets from one manifest

## Install

### Claude Desktop

```json
{
  "mcpServers": {
    "keyid": {
      "command": "npx",
      "args": ["-y", "@keyid/agent-kit"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add keyid -- npx -y @keyid/agent-kit
```

### Cursor local

```json
{
  "mcpServers": {
    "keyid": {
      "command": "npx",
      "args": ["-y", "@keyid/agent-kit"]
    }
  }
}
```

### Cursor or Claude remote

```text
https://keyid.ai/mcp
```

Hosted mode creates a managed install identity for the connector and stores the private key encrypted at rest. Local mode uses the Ed25519 keypair supplied through `KEYID_PUBLIC_KEY` and `KEYID_PRIVATE_KEY`, or generates one if they are missing.

## Tools (64)

### Identity
| Tool | Description |
|------|-------------|
| `provision_identity` | Create or reveal the email identity for this MCP session. |
| `get_identity` | Fetch the current KeyID identity, address, phone, and reputation. |
| `request_phone_number` | Assign a phone number to the current KeyID identity. |

### Messages
| Tool | Description |
|------|-------------|
| `list_messages` | List email or SMS messages with search and inbox filters. |
| `wait_for_message` | Poll until a matching inbound message arrives. |
| `get_message` | Fetch the full details for a single message. |
| `send_email` | Send an email from the current identity. |
| `reply_to_message` | Reply to a message, optionally as reply-all. |
| `update_message` | Update message flags such as read or starred state. |

### Threads
| Tool | Description |
|------|-------------|
| `list_threads` | List conversation threads for the current identity. |
| `get_thread` | Fetch a thread and all of its messages. |

### Verification
| Tool | Description |
|------|-------------|
| `get_verification_codes` | Read OTP or verification codes from a message, or from the latest matching message. |
| `follow_verification_link` | Follow a verification link directly or from an extracted message link list. |

### Signup
| Tool | Description |
|------|-------------|
| `start_registration_session` | Start a signup session that correlates email, SMS, or TOTP artifacts for one service. |
| `list_registration_sessions` | List current and historical signup sessions for this identity. |
| `get_registration_session` | Fetch one signup session, including its latest artifact summary and lease state. |
| `wait_for_registration_artifact` | Poll a signup session until an artifact arrives or the session expires, blocks, or times out. |
| `get_registration_artifacts` | Fetch the normalized artifacts attached to a signup session in priority order. |
| `save_browser_state` | Store cookies and browser session state for a signup session in the KeyID vault. |
| `load_browser_state` | Load the saved browser state for a signup session. |
| `complete_registration_session` | Mark a signup session complete after the browser flow succeeds. |
| `block_registration_session` | Mark a signup session blocked and record why the flow could not continue. |

### TOTP
| Tool | Description |
|------|-------------|
| `list_totp_entries` | List registered authenticator/TOTP entries for the identity. |
| `get_totp_code` | Generate the current TOTP code for a stored authenticator entry. |

### Persona
| Tool | Description |
|------|-------------|
| `get_persona` | Fetch the synthetic persona used for registrations. |
| `create_or_update_persona` | Create a persona or update the existing one with explicit overrides. |
| `save_registration` | Create or update a registration record for an external service. |
| `list_registrations` | List saved service registrations. |
| `get_registration` | Fetch one registration record by ID. |

### Secrets
| Tool | Description |
|------|-------------|
| `list_secrets` | List vault keys without exposing secret values. |
| `get_secret` | Retrieve a decrypted vault entry by key. |
| `put_secret` | Create or update a vault entry. |
| `delete_secret` | Delete a vault entry. |

### Search
| Tool | Description |
|------|-------------|
| `web_search` | Search the web via Google. Returns titles, URLs, and snippets. Rate-limited to 100 searches per day. |

### Storage
| Tool | Description |
|------|-------------|
| `list_files` | List files stored for the current agent. |
| `store_file` | Upload or overwrite a file. Content should be base64-encoded for binary, or plain text (which will be base64-encoded automatically). |
| `get_file` | Download a stored file by key. Returns base64-encoded content. |
| `delete_file` | Delete a stored file by key. |

### Scheduling
| Tool | Description |
|------|-------------|
| `list_crons` | List cron jobs that fire webhooks on a schedule. |
| `create_cron` | Register a webhook URL to fire on a cron schedule. Standard 5-field cron: minute hour day month weekday. |
| `update_cron` | Update a cron job — change schedule, URL, or pause/resume. |
| `delete_cron` | Remove a scheduled webhook. |

### Pages
| Tool | Description |
|------|-------------|
| `list_pages` | List all pages owned by the current agent. |
| `create_page` | Claim a slug and create a new agent page. Slug must be 5+ chars, lowercase alphanumeric with hyphens. |
| `get_page` | Get details of an agent page by slug. |
| `update_page` | Update page title, description, or published status. |
| `delete_page` | Delete a page and all its files. |
| `upload_page_file` | Upload or update a file in an agent page. Content must be base64-encoded. Allowed types: HTML, CSS, JS, images, JSON, text. |
| `list_page_files` | List all files in an agent page. |
| `delete_page_file` | Delete a single file from an agent page. |

### Settings
| Tool | Description |
|------|-------------|
| `get_auto_reply` | Fetch the current auto-reply configuration. |
| `set_auto_reply` | Enable, disable, or edit the auto-reply responder. |
| `get_forwarding` | Fetch the current forwarding address. |
| `set_forwarding` | Set or clear the forwarding address. |
| `get_signature` | Fetch the current email signature. |
| `set_signature` | Set or clear the email signature. |

### Contacts
| Tool | Description |
|------|-------------|
| `list_contacts` | List saved contacts for the identity. |
| `upsert_contact` | Create a contact by email or update one by contact ID. |
| `delete_contact` | Delete a contact by ID. |

### Webhooks
| Tool | Description |
|------|-------------|
| `list_webhooks` | List webhook subscriptions for the identity. |
| `create_webhook` | Create a webhook subscription. |
| `get_webhook_deliveries` | Inspect recent webhook delivery attempts. |

### Insights
| Tool | Description |
|------|-------------|
| `get_metrics` | Fetch usage metrics for the current identity. |
| `get_reputation` | Fetch the current reputation score and factor breakdown. |

## Prompts (8)

| Prompt | Description |
|--------|-------------|
| `set-up-agent-communications` | Provision email, inspect identity, and enable the communication settings the user asks for. |
| `complete-email-verification` | Use the low-level verification tools to watch for one verification message and surface the best link or code. |
| `run-signup-session` | Start a signup session, keep browser state aligned, and finish or block the flow with explicit state. |
| `resume-signup-session` | Load saved browser state, continue a paused signup, and wait for the next artifact only if needed. |
| `fetch-latest-code` | Retrieve the newest verification code from email, SMS, or TOTP. |
| `triage-inbox` | List recent messages, highlight urgent items, and suggest the safest next reply action. |
| `autonomous-signup` | Create or update a persona, run a signup session, and record the completed registration with durable state. |
| `reply-conservatively` | Reply briefly, avoid inventing commitments, and keep tone factual. |

## Resources (7)

| Resource | Description |
|----------|-------------|
| `keyid://identity/current` | Current email, phone, and profile state. |
| `keyid://inbox/unread` | Recent unread inbound messages. |
| `keyid://reputation/current` | Current reputation score and factor breakdown. |
| `keyid://totp/services` | Stored TOTP entries. |
| `keyid://registrations/recent` | Recent service registrations. |
| `keyid://vault/keys` | Stored secret keys without their values. |
| `keyid://registration-sessions/active` | Recent signup sessions for the current identity, newest first. |

## Generated metadata

- MCP registry metadata: [server.json](server.json)
- DXT manifest: [manifest.json](manifest.json)
- Smithery config: [smithery.yaml](smithery.yaml)
- MCP docs hub: [https://keyid.ai/mcp](https://keyid.ai/mcp)

## Examples

- [Claude Desktop local](https://keyid.ai/mcp/claude)
- [Cursor local and remote](https://keyid.ai/mcp/cursor)
- [Registration sessions](https://keyid.ai/mcp/signup)
- [Verification workflow](https://keyid.ai/mcp/verification)
- [OTP and TOTP workflow](https://keyid.ai/mcp/otp)

## Changelog

https://github.com/KeyID-AI/KeyID/releases