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

# MCP Integration

> Extend goose with Model Context Protocol (MCP) servers for custom tools and capabilities

The Model Context Protocol (MCP) enables goose to integrate with external tools, data sources, and services. MCP servers provide tools, resources, and prompts that agents can use during task execution.

## What is MCP?

MCP is an open protocol for connecting AI agents to external capabilities. Think of it as a plugin system for AI - MCP servers expose functionality that goose can discover and use dynamically.

<CardGroup cols={3}>
  <Card title="Tools" icon="wrench">
    Functions the agent can call (e.g., file operations, API calls)
  </Card>

  <Card title="Resources" icon="database">
    Data sources the agent can read (e.g., databases, files)
  </Card>

  <Card title="Prompts" icon="message">
    Pre-defined prompt templates for common tasks
  </Card>
</CardGroup>

## Built-in Extensions

Goose includes several built-in MCP servers:

### Developer Extension

Code editing and shell access:

```yaml theme={null}
extensions:
  - type: builtin
    name: developer
```

**Provided Tools:**

* `read_file`: Read file contents
* `write_file`: Create or overwrite files
* `edit_file`: Patch existing files
* `run_command`: Execute shell commands
* `list_directory`: List directory contents

### AutoVisualiser

Data visualization and charting:

```yaml theme={null}
extensions:
  - type: builtin
    name: autovisualiser
```

**Provided Tools:**

* `create_chart`: Generate charts from data (line, bar, pie, scatter)
* `create_dashboard`: Multi-chart dashboards
* `save_visualization`: Export to PNG/SVG

### ComputerController

Web scraping and document processing:

```yaml theme={null}
extensions:
  - type: builtin
    name: computercontroller
```

**Provided Tools:**

* `web_scrape`: Extract content from web pages
* `cache_page`: Save pages for offline access
* `automation_script`: Browser automation workflows
* `read_pdf`: Extract text from PDF files
* `read_docx`: Parse Word documents

### Memory

Persistent storage across sessions:

```yaml theme={null}
extensions:
  - type: builtin
    name: memory
```

**Provided Tools:**

* `store_memory`: Save key-value pairs
* `retrieve_memory`: Fetch stored values
* `list_memories`: Browse all stored data
* `delete_memory`: Remove entries

Memories can be scoped globally or per-session and support categories and tags.

See the [Built-in Extensions API reference](/api/extensions/builtin) for complete documentation.

## Adding External Extensions

### Interactive Configuration

The easiest way to add extensions:

```bash theme={null}
goose configure
# Select "Extensions" > "Add extension"
```

The wizard will prompt for:

* Extension name
* Transport type (stdio, SSE)
* Command and arguments
* Environment variables

### Manual Configuration

Edit `~/.config/goose/config.yaml`:

```yaml theme={null}
extensions:
  - name: "filesystem"
    enabled: true
    transport:
      type: "stdio"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
```

<Warning>
  Always review what tools an extension provides before enabling it. Extensions have access to your system with the same permissions as the goose process.
</Warning>

## MCP Server Examples

### Filesystem Access

Provides file read/write operations:

```yaml theme={null}
extensions:
  - name: "filesystem"
    transport:
      type: "stdio"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "./"]
```

**Use case:** Reading and modifying files in your project directory.

### PostgreSQL Database

Query and manage PostgreSQL databases:

```yaml theme={null}
extensions:
  - name: "postgres"
    transport:
      type: "stdio"
      command: "uvx"
      args: ["mcp-server-postgres", "postgresql://localhost/mydb"]
    env:
      PGHOST: "localhost"
      PGDATABASE: "mydb"
      PGUSER: "${POSTGRES_USER}"
      PGPASSWORD: "${POSTGRES_PASSWORD}"
```

**Use case:** Running SQL queries, viewing schema, managing data.

<Tip>
  Environment variables support `${VAR_NAME}` substitution from your shell environment.
</Tip>

### GitHub Integration

Interact with GitHub repositories and issues:

```yaml theme={null}
extensions:
  - name: "github"
    transport:
      type: "stdio"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
```

**Use case:** Creating issues, reviewing PRs, searching code, managing releases.

### Slack Integration

Send messages and manage Slack workspaces:

```yaml theme={null}
extensions:
  - name: "slack"
    transport:
      type: "stdio"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-slack"]
    env:
      SLACK_BOT_TOKEN: "${SLACK_BOT_TOKEN}"
```

**Use case:** Posting updates, reading channels, managing notifications.

### Custom Python Server

Run your own MCP server:

```yaml theme={null}
extensions:
  - name: "my-tools"
    transport:
      type: "stdio"
      command: "python"
      args: ["-m", "my_mcp_server"]
    env:
      API_KEY: "${MY_API_KEY}"
```

See [Extension Development](/development/extension-development) for building custom servers.

## Transport Types

### stdio (Standard Input/Output)

Most common transport - communication via stdin/stdout:

```yaml theme={null}
transport:
  type: "stdio"
  command: "npx"
  args: ["-y", "@modelcontextprotocol/server-filesystem", "./"]
```

**Advantages:**

* Simple to implement
* Works with any language
* Portable across platforms

### SSE (Server-Sent Events)

HTTP-based transport for remote servers:

```yaml theme={null}
transport:
  type: "sse"
  url: "http://localhost:8000/sse"
  headers:
    Authorization: "Bearer ${API_TOKEN}"
```

**Advantages:**

* Remote server deployment
* Can serve multiple clients
* Works through firewalls

<Info>
  SSE requires a server implementing the MCP SSE specification. See the [MCP Protocol guide](/development/mcp-protocol) for details.
</Info>

## Extension Security

Goose includes several security features for extensions:

### Permission Prompts

By default, goose prompts before executing tools:

```
goose wants to run: read_file("/etc/passwd")
Allow? [y/n/always/never]:
```

Configure permission behavior:

```yaml theme={null}
preferences:
  permission_mode: "prompt"  # prompt, allow, deny
```

* **prompt**: Ask each time (default)
* **allow**: Auto-approve all tool calls
* **deny**: Block all tool execution

<Warning>
  Setting `permission_mode: allow` disables all safety prompts. Only use in trusted environments.
</Warning>

### Environment Variable Filtering

Goose filters sensitive environment variables before passing them to extensions. Variables like `API_KEY`, `TOKEN`, `SECRET`, and `PASSWORD` are not exposed unless explicitly specified in the extension configuration.

### Output Scanning

Extension outputs are scanned for:

* Potential malware patterns
* Command injection attempts
* Path traversal attacks

Suspicious output triggers warnings and optional blocking.

## Using Extensions in Sessions

### CLI

Extensions from your config are automatically available in sessions:

```bash theme={null}
goose session
```

The agent will discover and use tools as needed:

```
you: What files are in this directory?
goose: Let me check...
[Calling list_directory(".")]
goose: You have the following files: ...
```

### One-time Extension Use

Add an extension for a single session:

```bash theme={null}
goose session --extension="filesystem"
```

### Recipes

Specify required extensions in recipes:

```yaml theme={null}
name: "web-scraper"
extensions:
  - type: builtin
    name: computercontroller
  - type: stdio
    name: postgres
    command: uvx
    args: ["mcp-server-postgres", "postgresql://localhost/mydb"]
```

Goose will activate these extensions when the recipe runs.

## Discovering Extension Capabilities

### List Available Tools

View tools provided by extensions:

```bash theme={null}
goose session
# In the session:
you: What tools do you have?
```

The agent will list all available tools from enabled extensions.

### Programmatic Discovery

Using the server API:

```bash theme={null}
curl http://localhost:3000/agents/my-agent/tools
```

Returns JSON with tool schemas:

```json theme={null}
[
  {
    "name": "read_file",
    "description": "Read contents of a file",
    "inputSchema": {
      "type": "object",
      "properties": {
        "path": { "type": "string" }
      },
      "required": ["path"]
    }
  }
]
```

See the [Server API reference](/api/server/agents) for details.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Extension won't start">
    Check that:

    1. The command is in your PATH: `which npx` or `which python`
    2. Required dependencies are installed: `npm install -g` or `pip install`
    3. The extension has correct permissions to execute
    4. Review logs with `goose session --log-level debug`

    Common issues:

    * Node.js extensions require `npx` (comes with Node.js)
    * Python extensions may need `uvx` (install with `pip install uv`)
  </Accordion>

  <Accordion title="Tools not available in session">
    Verify that:

    1. The extension is enabled in config: `enabled: true`
    2. The extension started successfully (check logs)
    3. Tools were properly registered (look for "Registered tool: ..." in logs)
    4. No conflicting extensions with the same tool names
  </Accordion>

  <Accordion title="Permission denied errors">
    This usually means:

    1. The extension tried to access a file/resource it doesn't have permission for
    2. The goose process doesn't have necessary permissions

    Solutions:

    * Grant goose permission to the required resources
    * Adjust the extension's scope (e.g., filesystem path restrictions)
    * Run goose with appropriate permissions (avoid `sudo` unless necessary)
  </Accordion>

  <Accordion title="Extension crashes during execution">
    Debug steps:

    1. Enable debug logging: `goose session --log-level debug`
    2. Test the extension standalone (without goose)
    3. Check the extension's own logs (if it produces any)
    4. Verify all required environment variables are set
    5. Report bugs to the extension maintainer
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Extension Development" icon="code" href="/development/extension-development">
    Build your own MCP servers in Python, TypeScript, or Rust
  </Card>

  <Card title="MCP Protocol" icon="book" href="/development/mcp-protocol">
    Learn the Model Context Protocol specification
  </Card>

  <Card title="Built-in Extensions" icon="box" href="/api/extensions/builtin">
    Complete API reference for goose's built-in extensions
  </Card>

  <Card title="Recipes" icon="bookmark" href="/concepts/recipes">
    Use extensions in automated workflows
  </Card>
</CardGroup>