# Tools & MCP servers

Tools are the things the agent can actually *do* — read a file, run a command, search the web. This page lists what ships built in, and how to add more through MCP servers or your own code.

## Built-in tools

These are registered in every session. Each one is subject to your permission rules, so "available" doesn't mean "unattended."

### Files

| Tool    | What it does                                               |
| ------- | ---------------------------------------------------------- |
| `read`  | Read a file, with image support and large-file truncation. |
| `write` | Create a file or replace its contents.                     |
| `edit`  | Make a targeted change inside an existing file.            |
| `patch` | Apply a structured patch across files.                     |
| `glob`  | Find files by name pattern.                                |
| `grep`  | Search file contents, powered by ripgrep.                  |

### Running and delegating

| Tool       | What it does                                                        |
| ---------- | ------------------------------------------------------------------- |
| `shell`    | Run a command in your shell.                                        |
| `task`     | Delegate to a subagent. See [Agents & subagents](/terminal/agents). |
| `todo`     | Keep a visible task list for multi-step work.                       |
| `question` | Ask you a structured question mid-task.                             |

### Knowledge and context

| Tool        | What it does                                                                |
| ----------- | --------------------------------------------------------------------------- |
| `bridge`    | Structural code intelligence — semantic search, symbols, references, trace. |
| `memory`    | Recall, save, and forget durable facts across sessions.                     |
| `skill`     | Load a skill's instructions into the conversation.                          |
| `webfetch`  | Fetch and read a URL.                                                       |
| `websearch` | Search the web.                                                             |

> Note:
>
> `bridge` and `memory` are covered in depth in [Memory & context bridge](/terminal/memory-and-bridge). `websearch` availability depends on your provider or a configured search key.

Two more are behind experimental flags and off by default: an `lsp` tool for language-server queries, and a `plan` tool used by plan-mode switching in the CLI.

## MCP servers

**MCP** — the Model Context Protocol — is an open standard for giving an agent extra tools. A GitHub MCP server adds GitHub tools; a database MCP server adds query tools. V3Code Terminal connects to them as a client.

Run `/mcps` to toggle servers on and off for the current session, and `v3code mcp list` to see every configured server with its status.

### Local servers

A local server is a process V3Code starts and talks to over stdio.

```jsonc
{
  "mcp": {
    "my-tools": {
      "type": "local",
      "command": ["bun", "x", "some-mcp-server"],
      "environment": { "API_TOKEN": "..." },
      "enabled": true,
      "timeout": 5000,
    },
  },
}
```

| Field         | Meaning                                                       |
| ------------- | ------------------------------------------------------------- |
| `command`     | The command and arguments to launch, as an array.             |
| `cwd`         | Working directory. Relative paths resolve from the workspace. |
| `environment` | Environment variables for the server process.                 |
| `enabled`     | Whether it starts with the session.                           |
| `timeout`     | Request timeout in milliseconds. Defaults to 5000.            |

### Remote servers

A remote server is reached over HTTP.

```jsonc
{
  "mcp": {
    "company-api": {
      "type": "remote",
      "url": "https://mcp.example.com/sse",
      "headers": { "Authorization": "Bearer ..." },
      "enabled": true,
    },
  },
}
```

OAuth is detected automatically when the server advertises it. If the server needs specific client details, configure them under `oauth` — `clientId`, `clientSecret`, `scope`, and either `callbackPort` or a full `redirectUri`. The default callback is `http://127.0.0.1:19876/mcp/oauth/callback`. Set `"oauth": false` to switch auto-detection off.

> Note:
>
> **Keep credentials out of committed config.** A token in a project's `v3code.json` gets committed with it. Prefer environment variables, or put the server in your global `~/.config/v3code/v3code.json`.

### MCP tools ask permission too

Tools from an MCP server are not automatically trusted. They appear under their own tool names and can be governed by the same permission rules as anything else, so an unknown tool can be set to `ask` or denied outright.

## Your own tools

For something small and project-specific, you don't need a full MCP server. Drop a JavaScript or TypeScript file into a `tool/` folder in your config directory — `.v3code/tool/changelog.ts` — and its exported tools are registered automatically.

The file name becomes the namespace: a default export from `changelog.ts` registers as `changelog`, and a named export `recent` registers as `changelog_recent`.

Plugins can contribute tools the same way. List them under `plugin` in your configuration.

## Controlling what's available

Three levers, from blunt to precise:

### tools

A simple enable map in configuration. Good for turning something off globally.

### permission

The real control. Works per tool and per pattern, and is what agents use to constrain themselves.

### agent permission

Rules set inside an agent file apply only to that agent — how `explore` stays read-only.

## Related

[Permissions & privacy](/terminal/permissions-and-privacy) covers approval rules, [Configuration](/terminal/configuration) covers where these blocks live, and [MCP](/connect/mcp) covers the editor's MCP support.