# @agentkeys-io/mcp

An **MCP (Model Context Protocol) server** that lets AI agents manage credentials and make proxied API calls through [AgentKeys](https://agentkeys.io).

Store API keys in AgentKeys and let your agent use them safely through the proxy — without ever seeing the raw secrets.

---

## Quick Start

```bash
AGENTKEYS_API_KEY=ak_ws_xxxx npx @agentkeys-io/mcp
```

Get your workspace API key from **[app.agentkeys.io/settings](https://app.agentkeys.io/dashboard/settings)**.

---

## Configuration

| Environment Variable   | Required | Default                      | Description                                        |
|------------------------|----------|------------------------------|----------------------------------------------------|
| `AGENTKEYS_API_KEY`    | ✅ Yes   | —                            | Workspace API key (starts with `ak_ws_`)           |
| `AGENTKEYS_URL`        | No       | `https://app.agentkeys.io`   | AgentKeys web app URL                              |
| `AGENTKEYS_PROXY_URL`  | No       | `https://proxy.agentkeys.io` | AgentKeys proxy URL                                |

---

## MCP Client Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "agentkeys": {
      "command": "npx",
      "args": ["@agentkeys-io/mcp"],
      "env": {
        "AGENTKEYS_API_KEY": "ak_ws_your_key_here"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "agentkeys": {
      "command": "npx",
      "args": ["@agentkeys-io/mcp"],
      "env": {
        "AGENTKEYS_API_KEY": "ak_ws_your_key_here"
      }
    }
  }
}
```

### Windsurf / Cline

Same config format — add to your MCP settings:

```json
{
  "mcpServers": {
    "agentkeys": {
      "command": "npx",
      "args": ["@agentkeys-io/mcp"],
      "env": {
        "AGENTKEYS_API_KEY": "ak_ws_your_key_here"
      }
    }
  }
}
```

---

## Available Tools

### Credential Management

#### `list_credentials`
List all credentials stored in the workspace.

#### `create_credential`
Create a new credential in the workspace.

| Parameter      | Type     | Required | Description |
|---------------|----------|----------|-------------|
| `name`        | string   | ✅       | Unique name for this credential |
| `type`        | string   | ✅       | `API_KEY` \| `BASIC_AUTH` \| `CUSTOM_HEADER` \| `QUERY_PARAM` \| `COOKIE` |
| `value`       | string   | For `API_KEY` | The secret value |
| `provider`    | string   | No       | Provider name (e.g. `stripe`, `resend`, `github`) |
| `baseUrl`     | string   | No       | Provider API base URL (e.g. `https://api.resend.com`) |

#### `delete_credential`
Delete a credential by ID. Also revokes all associated proxy tokens.

### Agent Management

#### `list_agents`
List all agents in the workspace.

#### `create_agent`
Create a new agent identity.

| Parameter     | Type   | Required | Description |
|--------------|--------|----------|-------------|
| `name`        | string | ✅       | Agent name (e.g. `marketing-bot`) |
| `description` | string | No       | What this agent does |

#### `assign_credential`
Assign a credential to an agent. Returns a **proxy token**.

⚠️ **The proxy token is shown once — store it securely.**

### Proxy Requests

#### `proxy_request`
Make an API call through the AgentKeys proxy.

| Parameter    | Type   | Required | Description |
|-------------|--------|----------|-------------|
| `proxyToken` | string | ✅       | Proxy token (starts with `pxr_`) |
| `url`        | string | ✅       | Target URL (e.g. `https://api.resend.com/emails`) |
| `method`     | string | No       | HTTP method (default: `GET`) |
| `headers`    | object | No       | Additional request headers |
| `body`       | string | No       | JSON string body |

---

## Typical Workflow

```
1. list_credentials          → see what's available
2. create_agent              → create agent for this task
3. assign_credential         → get proxy token
4. proxy_request             → call API using proxy token
```

---

## Links

- [Dashboard](https://app.agentkeys.io)
- [Docs](https://agentkeys.io/docs)
- [Support](mailto:support@agentkeys.io)