npm package: @getaid/mcp-server
Description: MCP server for querying the getaid.dev agent identity registry
Latest version: 1.0.1

# @getaid/mcp-server

MCP (Model Context Protocol) server for querying the [getaid.dev](https://getaid.dev) universal AI agent identity registry.

Enables any MCP-compatible AI agent or client (Claude, etc.) to look up agent identities, verify trust levels, and perform cryptographic identity challenges against the getaid.dev registry.

## Installation

### Claude Desktop

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

```json
{
  "mcpServers": {
    "getaid": {
      "command": "npx",
      "args": ["-y", "@getaid/mcp-server"],
      "env": {
        "GETAID_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add getaid -- npx -y @getaid/mcp-server
```

### Manual / Other MCP Clients

```bash
npx @getaid/mcp-server
```

## Configuration

| Environment Variable | Description                    | Default                   |
| -------------------- | ------------------------------ | ------------------------- |
| `GETAID_API_URL`     | Base URL of the getaid.dev API | `https://getaid.dev`      |
| `GETAID_API_KEY`     | API key for higher rate limits | None (public rate limits) |

## Tools

### `lookup_agent`

Look up a full agent profile by AID or handle.

| Parameter | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| `aid`     | string | No\*     | Agent ID (e.g. `AID-000012347`)            |
| `handle`  | string | No\*     | Agent handle (e.g. `@johndoe/trading-bot`) |

\* At least one of `aid` or `handle` must be provided.

### `search_agents`

Search the agent directory with filters.

| Parameter          | Type   | Required | Description                                                  |
| ------------------ | ------ | -------- | ------------------------------------------------------------ |
| `query`            | string | Yes      | Search query                                                 |
| `status`           | string | No       | Filter by status (comma-separated)                           |
| `verificationTier` | string | No       | Filter by tier (comma-separated)                             |
| `capabilities`     | string | No       | Filter by capabilities (comma-separated)                     |
| `tags`             | string | No       | Filter by tags (comma-separated)                             |
| `protocols`        | string | No       | Filter by protocols (MCP, A2A, REST, GraphQL, gRPC)          |
| `sortBy`           | string | No       | `relevance`, `newest`, `verification_tier`, `last_heartbeat` |
| `limit`            | number | No       | Results per page (1–100)                                     |
| `cursor`           | string | No       | Pagination cursor                                            |

### `verify_agent`

Quick trust check — returns AID validity, verification tier, and status.

| Parameter | Type   | Required | Description        |
| --------- | ------ | -------- | ------------------ |
| `aid`     | string | Yes      | Agent ID to verify |

### `get_agent_status`

Get heartbeat/liveness status of an agent.

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `aid`     | string | Yes      | Agent ID    |

### `get_public_key`

Get an agent's Ed25519 public key for signature verification.

| Parameter | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `aid`     | string | Yes      | Agent ID    |

### `create_challenge`

Issue a cryptographic identity challenge. Returns a nonce the agent must sign.

| Parameter | Type   | Required | Description           |
| --------- | ------ | -------- | --------------------- |
| `aid`     | string | Yes      | Agent ID to challenge |

### `verify_challenge`

Verify a signed challenge response to confirm agent identity.

| Parameter   | Type   | Required | Description                   |
| ----------- | ------ | -------- | ----------------------------- |
| `aid`       | string | Yes      | Agent ID                      |
| `nonce`     | string | Yes      | Nonce from `create_challenge` |
| `signature` | string | Yes      | Hex-encoded Ed25519 signature |

## Cryptographic Verification Flow

To verify an agent's identity:

1. Call `create_challenge` with the agent's AID → receive a `nonce`
2. The agent signs the nonce with its Ed25519 private key
3. Call `verify_challenge` with the AID, nonce, and signature → receive verification result

## Development

```bash
# Run tests
pnpm test

# Type check
pnpm typecheck

# Build
pnpm build
```

## License

MIT