> For the complete documentation index, see [llms.txt](https://docs.currents.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.currents.dev/ai/reference/mcp-server.md).

# MCP tools and permissions

Every tool of the Currents MCP server, what it does and the permission it needs, and how the hosted and local servers differ

The Currents MCP server gives an agent these tools. Each tool needs one permission. A connection to the [hosted server](/ai/connect/remote.md) lists only the tools its permissions cover. The [local server](/ai/connect/local.md) lists every tool, and the API key refuses what it does not allow.

To set up an agent, see [Connect your agent](/ai/connect.md).

## Tools

| Tool                                    | What it does                                                                                           | Permission       |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------- |
| `currents-get-projects`                 | Lists the projects                                                                                     | `projects:read`  |
| `currents-get-project`                  | Gets one project and its settings                                                                      | `projects:read`  |
| `currents-list-project-terms`           | Lists the tags, branches, authors and other values in a project's runs                                 | `projects:read`  |
| `currents-get-runs`                     | Lists a project's runs, filtered by branch, tag, status, date or text                                  | `results:read`   |
| `currents-get-run-details`              | Gets one run: its status, commit, branch, groups and spec files                                        | `results:read`   |
| `currents-find-run`                     | Finds the latest completed run by CI build ID, branch or tags                                          | `results:read`   |
| `currents-get-spec-instance`            | Gets the raw result of one spec file execution                                                         | `results:read`   |
| `currents-get-test-results`             | Gets the history of one test                                                                           | `results:read`   |
| `currents-get-context`                  | Gets why tests failed: the errors, steps and files of a run, a spec file or a test                     | `results:read`   |
| `currents-get-test-evidence`            | Lists the screenshots, videos, traces and attachments of each test in a CI run                         | `results:read`   |
| `currents-create-evidence-links`        | Creates a [trace link](/ai/agentic-artifacts/explore-a-trace.md) for a test attempt or a session trace | `results:read`   |
| `currents-list-pull-requests`           | Lists a project's pull requests with their runs                                                        | `results:read`   |
| `currents-get-project-insights`         | Gets run and test metrics for a project over time                                                      | `analytics:read` |
| `currents-get-spec-files-performance`   | Ranks spec files by duration, failures or flakiness                                                    | `analytics:read` |
| `currents-get-tests-performance`        | Ranks tests by failures, flakiness or duration                                                         | `analytics:read` |
| `currents-get-errors-explorer`          | Groups and counts errors across runs                                                                   | `analytics:read` |
| `currents-list-actions`                 | Lists the actions: rules that skip, quarantine or tag tests                                            | `actions:read`   |
| `currents-get-action`                   | Gets one action and its conditions                                                                     | `actions:read`   |
| `currents-list-affected-tests`          | Lists the tests that actions applied to                                                                | `actions:read`   |
| `currents-get-affected-test-executions` | Lists the executions of one test that an action applied to                                             | `actions:read`   |
| `currents-get-action-executions`        | Lists the test executions that one action applied to                                                   | `actions:read`   |
| `currents-create-action`                | Creates an action                                                                                      | `actions:write`  |
| `currents-update-action`                | Changes an action                                                                                      | `actions:write`  |
| `currents-delete-action`                | Archives an action                                                                                     | `actions:write`  |
| `currents-enable-action`                | Turns an action on                                                                                     | `actions:write`  |
| `currents-disable-action`               | Turns an action off                                                                                    | `actions:write`  |
| `currents-create-session`               | Creates a [session](/ai/reference/sessions.md) and returns upload URLs for its files                   | `runs:write`     |
| `currents-add-attachments`              | Adds files to a session or a CI run                                                                    | `runs:write`     |
| `currents-cancel-run`                   | Cancels a run in progress                                                                              | `runs:write`     |
| `currents-cancel-run-github-ci`         | Cancels the run of a GitHub Actions workflow run                                                       | `runs:write`     |
| `currents-reset-run`                    | Resets the failed spec files of a run so they run again                                                | `runs:write`     |
| `currents-delete-run`                   | Deletes a run and all its data, permanently                                                            | `runs:write`     |
| `currents-create-share-link`            | Creates a public [share link](/ai/reference/share-links.md) to a run, a spec file, a test or a session | `shares:write`   |
| `currents-list-webhooks`                | Lists a project's webhooks                                                                             | `webhooks:read`  |
| `currents-get-webhook`                  | Gets one webhook                                                                                       | `webhooks:read`  |
| `currents-create-webhook`               | Creates a webhook that sends run events to a URL                                                       | `webhooks:write` |
| `currents-update-webhook`               | Changes a webhook                                                                                      | `webhooks:write` |
| `currents-delete-webhook`               | Deletes a webhook, permanently                                                                         | `webhooks:write` |
| `currents-list-jira-projects`           | Lists the projects in your connected Jira                                                              | `issues:write`   |
| `currents-list-jira-issue-types`        | Lists the issue types and fields of a Jira project                                                     | `issues:write`   |
| `currents-create-jira-issue`            | Creates a Jira issue for a test in a run                                                               | `issues:write`   |
| `currents-link-jira-issue`              | Links an existing Jira issue to a test in a run                                                        | `issues:write`   |
| `currents-get-tests-signatures`         | Computes the ID Currents gives a test from the project, spec file path and test title. Reads no data.  | Every connection |

## Tools to grant with care

* `currents-delete-run` and `currents-delete-webhook` cannot be undone, and Currents does not ask for confirmation. Grant `runs:write`, `webhooks:write` or a **Read & Write** key only to an agent that needs them.
* Some tools reach beyond Currents. The Jira tools read and write issues in your connected Jira. The webhook tools store a URL that Currents later sends run data to. `currents-create-share-link` creates a link that anyone can open.

The server also gives a connected agent [skills](/ai/agent-skills/agent-skill-currents-mcp.md): the steps an agent follows for a task.

## Hosted or local

[MCP](https://modelcontextprotocol.io/introduction) (Model Context Protocol) is an open standard for giving an AI agent tools. Currents serves the same tools two ways:

|               | [Hosted](/ai/connect/remote.md)               | [Local](/ai/connect/local.md)             |
| ------------- | --------------------------------------------- | ----------------------------------------- |
| Address       | `https://mcp.currents.dev/mcp`                | The `@currents/mcp` npm package           |
| Runs          | Hosted by Currents                            | On your machine                           |
| Credentials   | A sign-in, or an API key                      | API key only                              |
| Acts as       | The person who signed in, in one organization | The organization the key belongs to       |
| Tool list     | The tools the connection was granted          | Every tool                                |
| Stays current | Ships with Currents                           | Fetched again by the client on each start |

Use the hosted server unless your client can only start local servers. It needs nothing installed, and a sign-in gives each person access that follows their own role, which an admin can revoke without changing a shared key.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.currents.dev/ai/reference/mcp-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.