🐣 Good first issue: contribute a new MCP adapter

[keysersoft]

👋 New here? Adding a pre-built MCP adapter is the most beginner-friendly way to contribute. It's typically a single JSON file and takes ~30 minutes once you've picked a target.

Claimed targets

Comment below to claim one. A claim without a PR for 14 days goes back in the pool, no hard feelings, life happens.

target	who	since	PR
GitLab	@ndycode	30 Aug 2026	(none yet, free again on 20 Sep if nothing lands)
Sentry	@Nagharjun17	12 Sep 2026	#551, small changes requested
Airtable	@Rudra-G-23	13 Sep 2026	#610 ✅ merged
Matomo	@dor1smeow	16 Sep 2026

Pick a target

Anything with a public API is welcome. The ones we'd be happiest about right now, because people ask for them and nobody has them yet: GitLab, Odoo, Kaufland Marketplace, Zalando Partner, Matomo, Business Central. Before you claim one, check packages/backend/src/adapters/ for the slug: the list above used to name OpenWeather, Freshdesk, Toggl and Harvest, which have all shipped since, and that cost someone a wasted claim. The community wishlist is the place to propose others. Check the table above and the open PRs so we don't duplicate effort, then comment here saying which one you'll work on.

Step-by-step

1. Fork the repo and create a branch (adapter/<saas-slug>).
2. Pick an existing adapter close to yours as a template, they all live under packages/backend/src/adapters/<region>/:
   • For a REST API with a token: intl/coingecko.json or de/dhl-tracking.json
   • For a REST API where an account id has to go into the path: intl/whatsapp-business.json (see the {{ENV_VAR}} placeholders)
   • For a GraphQL service: intl/shopware-6.json
   • For an API without auth at all: de/vies-vat.json
3. Copy it, rename it your-saas.json, and update slug, name, description, instructions, baseUrl, the authType/authConfig block and requiredEnvVars, then the tools[], one entry per endpoint you want to expose.
4. Run node scripts/regenerate-catalog.mjs. It rewrites packages/backend/src/adapters/catalog.ts for you, please don't edit that file by hand.
5. Run node scripts/validate-adapters.mjs and npm test -w packages/backend. The validator now prints a rule id, the JSON path and a suggested fix for every blocking error, so read its output before asking. The parametrised packages/backend/src/adapters/catalog.spec.ts validates every adapter. If yours talks to a live API you can add an opt-in live spec next to it, intl/nominatim.live.spec.ts shows the pattern (skipped unless an env flag is set).
6. Open a PR. Tag @keysersoft for review.

What we look for in a good adapter

• ✅ Real, useful tools (not just "list everything")
• ✅ Clear description strings, the AI uses them to decide when to call the tool
• ✅ Path/query/body parameters mapped explicitly (don't rely on auto-detection alone)
• ✅ Auth correctly scoped (least privilege wins). If every call needs an account or org id, make it an env var and use {{MY_VAR}} in the path instead of a tool parameter
• ✅ At least one example value per tool
• ✅ Read-only first. Write tools are fine in a second PR once the read side works

You don't need to touch the website: the guide page, logo and marketplace listing are generated on our side after the merge.

Resources

• 📖 Tool Definition Format, the JSON schema
• 📖 Connector Guides
• 📖 Existing adapters, copy-paste-friendly templates
• 💬 Stuck? Ping us in Discussions / Q&A

We're happy to pair on the first PR, don't be shy 🙌

[ndycode]

I’d like to contribute the GitLab adapter. I’ll keep the first PR read-only and focused on projects, issues, merge requests, and pipelines. It will use explicit parameters, least-privilege authentication guidance, catalog registration, examples, and focused tests where catalog validation is not sufficient. I confirmed GitLab is not currently implemented or reserved.

[Nagharjun17]

Hey, I’d like to work on adding a Sentry adapter as my first contribution. I’m planning to start with a few read-only endpoints for projects, issues, events and releases.

API docs: https://docs.sentry.io/api/

Let me know if someone is already working on this.

[Rudra-G-23]

I’d like to work on an Airtable adapter. I checked the current marketplace and open PRs and couldn’t find an existing or claimed Airtable adapter.

I’ll keep the first version read-only and focused on bases, table/schema metadata, and records, using scoped Personal Access Token authentication and explicit path/query parameters.

[keysersoft]

Sorry for the silence here, the last days went into the Claude directory submission. Catching up with all three of you in one go.

@Nagharjun17 Sentry: reviewed on #551, thanks, it's close. Two small changes and it goes in.

@Rudra-G-23 Airtable is yours, go ahead. Read only with a scoped personal access token is exactly the right first cut. Tip from having done a few of these: the record endpoint is /v0/{baseId}/{tableIdOrName} and the useful query params are filterByFormula, view, pageSize, maxRecords and offset. Metadata lives under /v0/meta/bases and /v0/meta/bases/{baseId}/tables. intl/coingecko.json is a compact REST template to start from. Keep the filterByFormula description concrete with one example formula, the model is much better at using it when it has seen one.

@ndycode are you still on GitLab? No pressure at all, just want to avoid someone else waiting on it. If nothing lands by 20 Sep I'll put it back in the pool.

For everyone: I rewrote the steps at the top of this issue, the old text pointed at a catalog file and a test folder that no longer exist. catalog.ts is generated now, run node scripts/regenerate-catalog.mjs and node scripts/validate-adapters.mjs before pushing. There's also a table of claimed targets up there and a short list of adapters we'd love to see (GitLab, Odoo, Kaufland, Zalando, OpenWeather, Matomo, Freshdesk, Toggl, Harvest). And if you hit the "list tools only return one page" problem, that's ours, not yours: #557.

[Rudra-G-23]

Please review @keysersoft : #610

[dor1smeow]

Hi, I'd like to work on the OpenWeather adapter.

I'll keep the first version read-only and focus on current weather,
forecast, and geocoding endpoints. I'll use explicit parameters,
API-key authentication, useful example values, and run the adapter
validation and backend tests before opening the PR.

[keysersoft]

@dor1smeow thanks for stepping up, and sorry, this one is on me: OpenWeather has been in the catalog since May. It lives at packages/backend/src/adapters/intl/openweather.json and it already covers current weather, the 5 day forecast, direct and reverse geocoding and air pollution, which is exactly the scope you described. The target list in this issue was out of date and I have just rewritten it. Nothing on your side, you had no way of knowing.

What is genuinely free right now, and where people keep asking: GitLab (claimed, but back in the pool on 20 Sep if nothing lands), Odoo, Kaufland Marketplace, Zalando Partner, Matomo, Business Central. If you want something else entirely that is fine too, just check packages/backend/src/adapters/ for the slug first so we do not repeat today.

If you would rather stay on weather, the only piece we are missing is One Call 3.0, but that needs its own OpenWeather subscription, so it is a thinner first contribution than a new system.

Two more things for everyone reading:

@Nagharjun17 Sentry is still waiting on the two small changes from my review, ping me if anything there is unclear.

@Rudra-G-23 Airtable is reviewed and I pushed the catalog count bump to your branch myself, see #610. The CLA signature is the only thing left.

[Rudra-G-23]

@keysersoft CLA signature was done

[dor1smeow]

Thanks for clarifying! I’d like to claim the Matomo adapter.

I checked packages/backend/src/adapters/ in the current repository and couldn’t find an existing Matomo adapter.

I’ll keep the first PR read-only and focus on useful reporting tools such as visit summaries, top pages, referrer types, visitor countries, and device types. I’ll use environment variables for the Matomo instance URL, site ID, and authentication token, and I’ll run the adapter validation and backend tests before opening the PR.

Please mark Matomo as claimed.

[keysersoft]

Matomo is yours, marked in the table. Your scope is the right one, visits summary, top pages, referrers, countries and devices is exactly what people ask an agent for.

Four things that will save you a couple of hours, because Matomo does not look like the other adapters:

It is one endpoint, not many. The whole Reporting API is GET /index.php with module=API and a method= naming the report. Literal values in queryParams are passed through as-is by our engine, so each tool pins its own report:

"endpointMapping": {
  "method": "GET",
  "path": "/index.php",
  "queryParams": {
    "module": "API",
    "method": "VisitsSummary.get",
    "format": "JSON",
    "idSite": "{{MATOMO_SITE_ID}}",
    "period": "$period",
    "date": "$date"
  }
}

The instance URL is an env var. "baseUrl": "{{MATOMO_URL}}", same as de/xentral.json, so the adapter works for Matomo Cloud and for self-hosted alike. MATOMO_SITE_ID as an env var too, as you planned: nobody wants the agent guessing the site id.

Auth. authType: "QUERY_AUTH" with authConfig: { "token_auth": "{{MATOMO_AUTH_TOKEN}}" }. The engine spreads authConfig into the query string verbatim, so the parameter name is whatever you write there, see de/here-geocoding.json which uses apiKey. One warning: recent Matomo can be configured to refuse token_auth in the URL and accept it only as a POST parameter. Test against a real instance, and if yours refuses it, say so on the PR and we will switch the tools to POST with a bodyTemplate, de/mfr-fieldservice.json is the reference for that.

Descriptions carry everything here. Since every tool has the same path, the model can only tell them apart from the name and the description. Spell out what the report returns and give a real period and date pair in the examples, period=day with date=today, and mention the range form date=2026-09-01,2026-09-15. For the top pages report filter_limit is worth exposing, the default of 100 is often not what you want.

Read-only first is right. Ping me on the PR when it is up, and note that fork PRs here need me to approve the workflows by hand before CI runs, so if the checks look empty it is me, not you.