Write your first plugin

Build a complete working plugin from an empty directory, load it into the server, connect it, and call its tool from an agent.

This walks through a real, shipped plugin end to end: google-gemini. It is the smallest complete OAuth plugin in the repo — one manifest, one tool — and all three of its files are short enough to read in full. Build the same shape in a directory of your own and you have a working integration.

mkdir -p /srv/awb-plugins/google-gemini/tools

// manifest.ts
export default {
  name: "google-gemini",
  version: "1.0.0",
  displayName: "Google Gemini",
  description: "Gemini generative AI models.",
  logo: "logo.svg",
  categories: ["google","ai"],
  auth: {
    type: "oauth2",
    authorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth",
    tokenUrl: "https://oauth2.googleapis.com/token",
    scopes: ["https://www.googleapis.com/auth/generative-language.retriever"],
  },
  proxy: { baseUrl: "https://generativelanguage.googleapis.com/v1beta" },
};

// tools/gemini.ts
import { z } from "zod";

export const generateContent = {
  name: "google_gemini_generate",
  description: "Generate content with Google Gemini",
  integration: "google-gemini",
  inputSchema: z.object({
    prompt: z.string(),
    model: z.string().default("gemini-1.5-flash"),
  }),
  handler: async (ctx: any, args: any) => {
    const res = await ctx.http(
      `https://generativelanguage.googleapis.com/v1beta/models/${args.model}:generateContent`,
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          contents: [{ parts: [{ text: args.prompt }] }],
        }),
      }
    );
    return res.json();
  },
};

// tools/index.ts
export { generateContent } from "./gemini";

# .env
PLUGINS_DIR=/srv/awb-plugins
GOOGLE_GEMINI_CLIENT_ID=...
GOOGLE_GEMINI_CLIENT_SECRET=...

${SERVER_PUBLIC_URL}/api/auth/plugin/google-gemini/callback

Loaded plugin: google-gemini

connect({ integration: "google-gemini" })
→ { url, connectionId }

wait_for_connection({ connectionId })
→ { status: "CONNECTED" }

{
  "executions": [
    {
      "tool": "google_gemini_generate",
      "args": { "prompt": "Summarise the CAP theorem in two sentences." }
    }
  ]
}

curl -s -X POST $SERVER_PUBLIC_URL/mcp \
  -H "x-workbench-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search_tools","arguments":{"query":"gemini"}}}'

What makes an export a tool#

The loader does not read a registry file or a decorator. It iterates every export of tools/index.ts and keeps the values that pass a duck-type check:

An export that fails any of the first four is silently ignored: helper functions, constants, and types can live in the same barrel without trouble. An export that passes them but omits description or integration registers and then breaks at runtime — integration is what the executor uses to look up the auth config and build the context, and description is what tool search matches on. Always set all five.

inputSchema must be Zod, not JSON Schema#

This is the single most common mistake. A JSON-Schema object fails the instanceof z.ZodType check, so the export is not recognised as a tool at all and your plugin loads with zero tools and no error message.

Zod is required because the schema is used two ways:

• Validation. Args are safeParsed against it before the handler runs, so .default() values are materialised and the handler sees a fully-populated object. A parse failure returns { error: "Invalid arguments for <tool>: …" } and the handler is never called.
• Publication. get_tool_schema converts it with zodToJsonSchema so any MCP client can consume a portable JSON Schema without knowing about Zod.

inputSchema: z.object({          // correct
  query: z.string(),
  limit: z.number().default(10),
}),

inputSchema: {                   // wrong — the tool will not register
  type: "object",
  properties: { query: { type: "string" } },
},

What the handler can assume#

By the time your handler runs, the executor has already:

• confirmed the integration is connected, returning { error: "NOT_CONNECTED", integration, message } to the agent if not (auth.type: "none" counts as always connected, cookie checks for live cookies, and everything else requires a stored token)
• validated and defaulted the args
• built the ToolContext for (userId, tool.integration).

Handlers do not need to catch their own errors — a throw is caught and converted to { error } for that execution entry.

Audit logging and metrics do not cover the same ground:

The counters are incremented only around handler execution, so a burst of NOT_CONNECTED results or schema-validation failures never appears in tool_executions_total. Alert on the audit log, not that series, if you need to catch those.