Skip to main content
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.

Tools

Functions the agent can call (e.g., file operations, API calls)

Resources

Data sources the agent can read (e.g., databases, files)

Prompts

Pre-defined prompt templates for common tasks

​
Built-in Extensions

Goose includes several built-in MCP servers:

​
Developer Extension

Code editing and shell access: 
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: 
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: 
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: 
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 for complete documentation.

​
Adding External Extensions

​
Interactive Configuration

The easiest way to add extensions: 
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: 
extensions:
  - name: "filesystem"
    enabled: true
    transport:
      type: "stdio"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
Always review what tools an extension provides before enabling it. Extensions have access to your system with the same permissions as the goose process.

​
MCP Server Examples

​
Filesystem Access

Provides file read/write operations: 
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: 
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.
Environment variables support ${VAR_NAME} substitution from your shell environment.

​
GitHub Integration

Interact with GitHub repositories and issues: 
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: 
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: 
extensions:
  - name: "my-tools"
    transport:
      type: "stdio"
      command: "python"
      args: ["-m", "my_mcp_server"]
    env:
      API_KEY: "${MY_API_KEY}"
See Extension Development for building custom servers.

​
Transport Types

​
stdio (Standard Input/Output)

Most common transport - communication via stdin/stdout: 
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: 
transport:
  type: "sse"
  url: "http://localhost:8000/sse"
  headers:
    Authorization: "Bearer ${API_TOKEN}"
Advantages:
  • Remote server deployment
  • Can serve multiple clients
  • Works through firewalls
SSE requires a server implementing the MCP SSE specification. See the MCP Protocol guide for details.

​
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: 
preferences:
  permission_mode: "prompt"  # prompt, allow, deny
  • prompt: Ask each time (default)
  • allow: Auto-approve all tool calls
  • deny: Block all tool execution
Setting permission_mode: allow disables all safety prompts. Only use in trusted environments.

​
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: 
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: 
goose session --extension="filesystem"

​
Recipes

Specify required extensions in recipes: 
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: 
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: 
curl http://localhost:3000/agents/my-agent/tools
Returns JSON with tool schemas: 
[
  {
    "name": "read_file",
    "description": "Read contents of a file",
    "inputSchema": {
      "type": "object",
      "properties": {
        "path": { "type": "string" }
      },
      "required": ["path"]
    }
  }
]
See the Server API reference for details.

​
Troubleshooting

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)
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
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)
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

​
Next Steps

Extension Development

Build your own MCP servers in Python, TypeScript, or Rust

MCP Protocol

Learn the Model Context Protocol specification

Built-in Extensions

Complete API reference for goose’s built-in extensions

Recipes

Use extensions in automated workflows

Build docs developers (and LLMs) love

Get started for freeTalk to us