> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.deeto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server — API Keys

> Programmatic, token-based access to the Deeto MCP Server — privilege levels, key management, making your first call, and how to connect to Claude Desktop.

<Tip>
  Connecting Claude, ChatGPT, Cursor, or another app through its own UI? Use [OAuth](/integrations/mcp-server-getting-started) instead — no key to manage, and it's the default for most users. This page covers **API keys**: a token-based path for scripts, backend services, and custom integrations that call the Deeto MCP Server directly.
</Tip>

The Deeto MCP Server uses API keys for authentication. Each key carries a privilege level that controls which tools it can access.

***

## API key format

All requests require an API key in the `Authorization` header:

```http theme={null}
Authorization: Bearer dtk_live_your_api_key_here
```

Keys always start with the `dtk_live_` prefix.

***

## Privilege levels

Privileges are hierarchical — higher levels inherit all permissions from lower levels.

| Rank | Privilege      | API value       | Capabilities                                                            |
| ---- | -------------- | --------------- | ----------------------------------------------------------------------- |
| 0    | Content Viewer | `contentViewer` | Read-only access to people, companies, content, and stats               |
| 1    | Rep            | `rep`           | Content Viewer + prospect dashboard, content instructions               |
| 2    | Manager        | `manager`       | Rep + start-agent for automated AI workflows                            |
| 3    | Admin          | `admin`         | Manager + create companies, people, and content drafts; manage API keys |
| 4    | Deeto Admin    | `deetoAdmin`    | Full platform access (Deeto internal use)                               |

### Tool-to-privilege mapping

| Tool                       | Minimum privilege |
| -------------------------- | ----------------- |
| `get-stats`                | contentViewer     |
| `get-people`               | contentViewer     |
| `get-companies`            | contentViewer     |
| `get-contents`             | contentViewer     |
| `get-prospects-dashboard`  | rep               |
| `get-content-instructions` | rep               |
| `start-agent`              | manager           |
| `create-company`           | admin             |
| `create-person`            | admin             |
| `save-draft-content`       | admin             |

***

## Generating a key

Only workspace **Admins** and **Deeto Admins** can generate API keys. When creating a key, specify:

* **Name** — a descriptive label
* **Privilege** — the access level for this key

Keys always follow this format:

```
dtk_live_abc123def456...
```

<Warning>
  The full API key is returned **only once** at creation time. Store it securely — it cannot be retrieved later. Only a truncated preview is shown in the management UI.
</Warning>

<Note>
  You cannot create a key with a higher privilege level than your own. An Admin cannot create a Deeto Admin key.
</Note>

***

## Making your first API call

Once you have a key, here's how to start using it.

<Steps>
  <Step title="Initialize the connection">
    Send an `initialize` request to establish the MCP session:

    ```http theme={null}
    POST https://api.deeto.ai/v2/mcp
    Authorization: Bearer dtk_live_your_api_key_here
    Content-Type: application/json

    {
      "jsonrpc": "2.0",
      "method": "initialize",
      "id": 1
    }
    ```

    **Response:**

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "result": {
        "protocolVersion": "2024-11-05",
        "capabilities": { "tools": {} },
        "serverInfo": {
          "name": "deeto-mcp-server",
          "version": "1.0.0"
        },
        "instructions": "..."
      },
      "id": 1
    }
    ```

    <Tip>
      Your `vendorId` is included in the `initialize` response `instructions` field. You do **not** need to pass it in any subsequent tool calls — the server reads it automatically from your API key.
    </Tip>
  </Step>

  <Step title="List available tools">
    Discover which tools your API key can access:

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "method": "tools/list",
      "id": 2
    }
    ```

    The response includes each tool's name, description, and input schema. Tools above your privilege level are not returned.
  </Step>

  <Step title="Make your first call">
    Start with `get-stats` for a quick workspace overview:

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "method": "tools/call",
      "params": {
        "name": "get-stats",
        "arguments": {}
      },
      "id": 3
    }
    ```

    **Response:**

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "result": {
        "content": [{
          "type": "text",
          "text": "{\"data\":{\"tools\":{\"get-people\":{\"total\":619},\"get-companies\":{\"total\":526},\"get-contents\":{\"total\":3322}},\"rewards\":{\"totalRedemptions\":124,\"totalRedeemedAmount\":9300,\"totalRedeemableAmount\":4150}}}"
        }]
      },
      "id": 3
    }
    ```
  </Step>

  <Step title="Query your data">
    Try querying references with filtering and pagination:

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "method": "tools/call",
      "params": {
        "name": "get-people",
        "arguments": {
          "userPrivileges": "reference",
          "page": 1,
          "pageSize": 10,
          "fields": ["basic", "status"]
        }
      },
      "id": 4
    }
    ```
  </Step>
</Steps>

***

## Key management

### Revoking keys

API keys can be revoked at any time by Admins or Deeto Admins. Revoked keys are **immediately** invalidated — there is no propagation delay.

### Key tracking

The system tracks when each key was last used. Use this to identify and clean up inactive keys.

### Key storage

Keys are stored as one-way SHA-256 hashes server-side. The plaintext key is shown only once and cannot be retrieved.

### Key management capabilities

| Capability                 | Supported         | Notes                                                       |
| -------------------------- | ----------------- | ----------------------------------------------------------- |
| Immediate revocation       | ✅ Yes             | Revoked keys rejected on next request, no propagation delay |
| Key rotation               | ✅ Yes             | Generate a new key and revoke the old one at any time       |
| Automatic expiration (TTL) | 🔄 In development | Keys can be manually revoked at any time in the interim     |
| IP allowlist               | ❌ No              | Not currently supported                                     |

***

## Authentication errors

| Scenario                 | Error code | Message                                                                                   |
| ------------------------ | ---------- | ----------------------------------------------------------------------------------------- |
| No auth header           | `-32001`   | Unauthorized: Bearer token required                                                       |
| Invalid or malformed key | `-32001`   | Unauthorized: Invalid API key                                                             |
| Revoked key              | `-32001`   | Unauthorized: API key has been revoked                                                    |
| Insufficient privilege   | `-32001`   | Forbidden: tool `<name>` requires `<required>` privilege but your API key has `<current>` |

***

## Best practices

* **Use minimum privilege** — Create keys with only the access level needed
* **Rotate keys regularly** — Revoke old keys and generate new ones periodically
* **One key per integration** — Use separate keys for different applications
* **Never expose keys** — Do not commit keys to source control or expose them client-side
* **Monitor usage** — Review last-used timestamps to identify inactive keys

***

## Connecting with Claude Desktop

Add this to your Claude Desktop MCP configuration file:

* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json theme={null}
{
  "mcpServers": {
    "deeto": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.deeto.ai/v2/mcp",
        "--header",
        "Authorization:${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "Bearer dtk_live_your_api_key_here"
      }
    }
  }
}
```

Replace `dtk_live_your_api_key_here` with your actual API key. After saving, restart Claude Desktop. A hammer icon confirms MCP tools are active.

<Warning>
  Your API key is stored in the config file on your local machine. Make sure this file is not shared or committed to version control.
</Warning>

Once connected, you can ask Claude things like:

* "How many references do we have?"
* "Show me all confirmed references at enterprise companies"
* "Find all quotes tagged with 'ROI'"
* "Find all quotes tagged with 'enterprise'"
* "Create a case study based on our Acme Corp references"

<Tip>
  Use a `contentViewer` key if you only need read access. Only use higher-privilege keys when you need to create records or manage content.
</Tip>

<Note>
  This is the API-key connection method. If you'd rather connect Claude Desktop (or any app) through a browser sign-in instead of managing a key, see [OAuth Getting Started](/integrations/mcp-server-getting-started).
</Note>

***

## Need help?

Contact your Deeto Customer Success Manager or email [support@deeto.ai](mailto:support@deeto.ai).