MCP

Introduction

GreyCat has a built-in MCP server. Any @expose function annotated with @tag("mcp") is automatically registered as an MCP tool, no extra server or adapter needed.

A function must be @expose to be reachable over HTTP. Adding @tag("mcp") on top of that makes it discoverable as an MCP tool. Functions that are only @expose (without @tag("mcp")) remain regular HTTP endpoints but are not visible to MCP clients.

Use @tag("mcp") sparingly — only expose high-value operations that an LLM agent would meaningfully use. Exposing too many tools degrades agent performance.

Defining tools

Annotate any @expose function with @tag("mcp") to make it available as an MCP tool:

@expose
@tag("mcp")
fn hello(name: String): String {
    return "Hello, ${name}";
}

Documentation

The /// doc comments above a function are sent as the tool description to the LLM agent. Use /// @param to describe each parameter:

/// Search cities by name prefix
/// @param prefix the beginning of the city name
/// @param limit maximum number of results to return
@expose
@tag("mcp")
fn searchCities(prefix: String, limit: int): Array<CityView> {
    // ...
}

Write clear, concise descriptions — this is how agents decide when and how to call your tools.

Tool naming

MCP tool names are derived from the fully qualified function name. A function hello in project.gcl becomes the tool project.hello. A function searchCities in src/cities.gcl becomes cities.searchCities.

Permissions

MCP tools respect GreyCat’s permission system. Use @permission to restrict access:

@expose
@tag("mcp")
@permission("admin")
fn deleteAllRecords() {
    // only callable with a token that has the "admin" permission
}

The token provided in the MCP client configuration determines which tools the agent can call.

Server setup

Start your GreyCat server:

greycat serve

Generate a token for a user by id:

TOKEN=$(greycat token --user=1 --validity=120day)

The token authenticates MCP clients against your GreyCat server. Pass it in the Authorization header when configuring your client (see Configuration below).

Configuration

CLIs

{
  // .mcp.json
  "mcpServers": {
    "greycat": {
      "type": "http",
      "url": "http://localhost:8080",
      "headers": {
        "Authorization": "YOUR_TOKEN_HERE"
      }
    }
  }
}

{
  // .gemini/settings.json
  "mcpServers": {
    "greycat": {
      "httpUrl": "http://localhost:8080",
      "headers": {
        "Authorization": "YOUR_TOKEN_HERE"
      }
    }
  }
}

# .codex/config.toml
[mcp_servers.greycat]
url = "http://localhost:8080"
http_headers = { "Authorization" = "YOUR_TOKEN_HERE" }

{
  // ~/.copilot/mcp-config.json
  "mcpServers": {
    "greycat": {
      "type": "http",
      "url": "http://localhost:8080",
      "headers": {
        "Authorization": "YOUR_TOKEN_HERE"
      }
    }
  }
}

{
  // .amazonq/mcp.json
  "mcpServers": {
    "greycat": {
      "type": "http",
      "url": "http://localhost:8080",
      "headers": {
        "Authorization": "YOUR_TOKEN_HERE"
      }
    }
  }
}

IDEs

{
  // claude_desktop_config.json
  "mcpServers": {
    "greycat": {
      "type": "http",
      "url": "http://localhost:8080",
      "headers": {
        "Authorization": "YOUR_TOKEN_HERE"
      }
    }
  }
}

{
  // .vscode/mcp.json
  "servers": {
    "greycat": {
      "type": "http",
      "url": "http://localhost:8080",
      "headers": {
        "Authorization": "YOUR_TOKEN_HERE"
      }
    }
  }
}

{
  // .cursor/mcp.json
  "mcpServers": {
    "greycat": {
      "type": "http",
      "url": "http://localhost:8080",
      "headers": {
        "Authorization": "YOUR_TOKEN_HERE"
      }
    }
  }
}

{
  // ~/.codeium/windsurf/mcp_config.json
  "mcpServers": {
    "greycat": {
      "type": "http",
      "serverUrl": "http://localhost:8080",
      "headers": {
        "Authorization": "YOUR_TOKEN_HERE"
      }
    }
  }
}

{
  // settings.json
  "context_servers": {
    "greycat": {
      "settings": {},
      "enabled": true,
      "url": "http://localhost:8080",
      "headers": {
        "Authorization": "YOUR_TOKEN_HERE"
      }
    }
  }
}

{
  // Settings | Tools | AI Assistant | MCP Servers
  "mcpServers": {
    "greycat": {
      "type": "http",
      "url": "http://localhost:8080",
      "headers": {
        "Authorization": "YOUR_TOKEN_HERE"
      }
    }
  }
}