MCP Tools Explained

MCP (Model Context Protocol) tools are the core mechanism by which your AI editor interacts with Conjra.

What is an MCP tool?

An MCP tool is a function that an AI assistant can call. Each tool has:

• A name — used by the AI to identify the tool (e.g., create_supabase_project)
• A description — helps the AI understand when to use this tool
• An input schema — parameters the AI must provide (defined with Zod)
• An execute function — the actual API call implementation

How tools are registered

When Conjra MCP server starts, it scans each provider module in src/mcp/tools/. Each module exports an array of tool objects, registered via server.tool(name, description, schema, handler).

The handler receives the raw input from the AI and credentials for the provider (auto-injected based on the tool name suffix).

Schema validation

Every tool input is validated against its Zod schema before execution. Example schema for create_supabase_project:

{
  name: z.string(),
  organizationId: z.string().optional(),
  region: z.string().optional(),
  dbPassword: z.string(),
}

Error handling

Tools handle errors at multiple levels:

1. Schema validation — Invalid input returns error before API call
2. Credential lookup — ProviderNotConnectedError if not connected
3. API errors — Wrapped in APIError with status codes
4. Auth errors — AuthError for authentication failures
5. Generic errors — All other failures caught and returned

Return values

Successful calls return a JSON object. The AI receives this and presents it naturally. For example, creating a Supabase project returns:

{
  "id": "abc-def-ghi",
  "name": "my-project",
  "database_url": "postgresql://...",
  "anon_key": "eyJhbGciOi...",
  "service_role_key": "eyJhbGciOi..."
}

Browse every available tool in the MCP Tools overview.