# Connect Tarkle to your AI agent

Tarkle lets an AI assistant upload files to a Tarkle workspace and create a public share link, acting as the signed-in user.

- MCP server (streamable HTTP): `https://mcp.tarkle.com/mcp`
- Authentication: `Authorization: Bearer <token>`
- Docs for people: https://tarkle.com/connect-ai

## Status
Tarkle checks each client's documented setup, but we are still verifying every client end to end. Browser sign-in (OAuth) is being rolled out client by client. Personal access tokens work with any client that can send an Authorization header.

## Step 1: get a token (the user does this)
Ask the user to open **Tarkle, Claude & Codex** (https://tarkle.com/dashboard/connect-ai), create an access token, and give it to you through an environment variable. Never print or store the token in files. Tokens are shown once, expire (90 days by default) and can be revoked.

## Step 2: add the server for the client you run in

### Claude Code

Create a token in Tarkle (Claude & Codex page), then run:

```bash
claude mcp add --transport http tarkle https://mcp.tarkle.com/mcp --header "Authorization: Bearer <your-tarkle-token>"
```

### Codex

Set TARKLE_MCP_TOKEN to your token, then run:

```bash
export TARKLE_MCP_TOKEN=<your-tarkle-token>
codex mcp add tarkle --url https://mcp.tarkle.com/mcp --bearer-token-env-var TARKLE_MCP_TOKEN
```

### Cursor

Cursor Settings, Tools & MCP, New MCP Server, then use:

```json
{
  "mcpServers": {
    "tarkle": {
      "url": "https://mcp.tarkle.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-tarkle-token>"
      }
    }
  }
}
```

### VS Code (GitHub Copilot)

VS Code uses a top-level `servers` key and requires `type: http`. Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "tarkle": {
      "type": "http",
      "url": "https://mcp.tarkle.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-tarkle-token>"
      }
    }
  }
}
```

### Windsurf

Windsurf uses `serverUrl`. Edit `~/.codeium/windsurf/mcp_config.json`, save and restart:

```json
{
  "mcpServers": {
    "tarkle": {
      "serverUrl": "https://mcp.tarkle.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-tarkle-token>"
      }
    }
  }
}
```

### Other MCP clients

Any client that supports remote (streamable HTTP) MCP servers with custom headers:

```json
{
  "mcpServers": {
    "tarkle": {
      "url": "https://mcp.tarkle.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-tarkle-token>"
      }
    }
  }
}
```

### Claude (web/desktop) and ChatGPT custom connectors

These clients only connect with browser sign-in (OAuth). Support will be announced once it is verified. Use Claude Code, Codex or Cursor with a token for now.

## Step 3: test
Ask: "List my Tarkle workspaces." A list of workspaces means the connection works. A 401 means the token is wrong, expired or revoked. A 404 means MCP is not enabled yet.

## What you can do
- `tarkle_list_workspaces`: See the workspaces you belong to.
- `tarkle_list_files`: Browse files already in a workspace.
- `tarkle_start_upload`: Start an upload and get secure upload URLs (your plan's storage limit applies).
- `tarkle_get_upload_parts`: Get more upload URLs for large multipart files.
- `tarkle_get_upload_status`: Check an upload and finish it once every byte has arrived.
- `tarkle_get_upload_page`: Get a browser upload link for files the assistant cannot read (for example chat attachments).
- `tarkle_create_transfer`: Create a public share link for files, audio or video. Tarkle sends no email.
- `tarkle_create_file_request`: Create a file request with a public submission link. Tarkle sends no email.
- `tarkle_list_file_requests`: List a workspace's file requests, filterable by active/completed.
- `tarkle_get_file_request_submissions`: List the files submitted to one file request.
- `tarkle_list_brands`: List a workspace's brands and each one's own brand-page domain, if any.

## Rules for agents
- Share links are public. Confirm with the user before creating one.
- Tarkle sends no email; give the link to the user.
- Uploads respect the user's plan storage limit. If the upload is refused, explain why instead of retrying.
- If you cannot read a file (for example a chat attachment), call `tarkle_get_upload_page` and ask the user to upload in the browser, then continue.