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

# MCP tools

> Twin a trace from an agent with the kennet MCP server.

The kennet MCP server provides three twin tools to sign-ins with twin access (`kennet:twin`). Files move through short-lived curl commands that run in the agent's shell, not through tool arguments.

| Tool | Description |
| - | - |
| `upload_trace` | Returns a curl command that uploads one trace from the working directory |
| `twin_trace` | Creates the twin of an uploaded trace. Returns a task |
| `pull_trace` | Returns a curl command that downloads a twin into the working directory |

Follow a task with `get_task`; cancel it with `cancel_task`.

## upload\_trace

| Argument | Type | Required | Description |
| - | - | - | - |
| `filename` | string | yes | The trace's file name in the working directory, such as `trace.jsonl`, in a [supported format](https://docs.metaphi.ai/kennet/api/files.md#formats) |

**Returns** `{upload_id, command, url, expires_at}`. Run `command` before `expires_at` (10 minutes).

## twin\_trace

| Argument | Type | Required | Description |
| - | - | - | - |
| `upload_id` | string | yes | The `upload_id` from `upload_trace`, after its command has run |
| `confidential` | array of strings | no | Public organisations to treat as confidential |

**Returns** a task. When it completes, its result has `output_path`; when it fails, an `error` with a [code](#tool-errors). Each upload is twinned once.

Errors on our side are retried automatically. If the organization's balance runs out, the twin pauses and resumes once credit is added.

## pull\_trace

| Argument | Type | Required | Description |
| - | - | - | - |
| `trace_path` | string | yes | The `output_path` from the completed task |

**Returns** `{command, url, expires_at}`. Run `command` before `expires_at` (10 minutes).

## Tool errors

The tools return the API's [error codes](https://docs.metaphi.ai/kennet/api/errors.md#codes), and these:

| Code | Cause |
| - | - |
| `invalid_upload_id` | `upload_id` was not returned by `upload_trace` |
| `upload_not_found` | No file was uploaded under `upload_id`. Run the upload command first |
| `upload_already_run` | The upload was already twinned. Upload the trace again |
| `invalid_output_path` | `trace_path` was not returned by a twin task |
| `output_not_found` | No file at `trace_path` |
| `task_not_found` | No such task for this sign-in |
| `not_text` | The uploaded file is not JSON, JSON Lines or UTF-8 text. Convert it and upload again |

For many traces, use [batches](https://docs.metaphi.ai/kennet/api/batches.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.