outsystems-mcp

Distribution repo for the OutSystems MCP. To install, paste the matching prompt below into your AI assistant.

Every harness section below sets up two artifacts and says how to keep the skill current. Your agent needs both: the MCP server without the skill gives it every tool and none of the rules, the confirm-before-destructive rule included, and the skill without the MCP server leaves it nothing to call. Some hosts deliver both in one step; the section says so when that is the case. The latest published skill is the one on the main branch of this repo; there are no release notes, so the commit history is where changes show up.

• Skill: the document that tells the agent how to work with OutSystems: confirm before changing tenant state, poll long-running operations until they finish, decide retries from the error category, prefer the asset key over names. It changes with new releases, so each section carries an Update step. Some hosts wrap it in a plugin or a Power.
• MCP server: the OutSystems endpoint at https://<my-tenant>/mcp, which exposes the tools and signs you in to your tenant. OutSystems hosts it and updates it on the tenant side, and your harness only stores its URL; if you reach it through the mcp-remote local proxy, as the Claude Desktop install does, keep mcp-remote at the exact version 0.14.3 the install pins (see Install - Claude Desktop).

Install - Claude Code

Skill and MCP server: one plugin install delivers both. The plugin carries the skill and declares the MCP server from your tenant hostname. Paste into Claude Code:

Install the OutSystems outsystems-mcp plugin from OutSystems/outsystems-mcp on GitHub.
Step 1: ask me for my OutSystems tenant hostname (something like `mycompany.outsystems.dev`). Strip any scheme, leading `www.`, trailing slash, and path or query, keeping only the host. If the result doesn't match `^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$`, ask again rather than proceeding with an unvalidated value: the next step does not validate it, and a value carrying a scheme prefix or a path produces a server URL that cannot resolve.
Step 2: run `claude plugin marketplace add OutSystems/outsystems-mcp`.
Step 3: run `claude plugin install outsystems@outsystems --config tenant_hostname=<my-tenant>`, where `<my-tenant>` is exactly the bare hostname from Step 1. The plugin declares the MCP server itself, at `https://<my-tenant>/mcp`, so there is no separate `claude mcp add` step. If `claude` rejects `--config`, my Claude Code predates plugin options: tell me to update Claude Code and re-run this step; if updating is not possible, install without `--config` and tell me to run `/plugin configure outsystems@outsystems` and type that same bare hostname there. Never add a `--client-id` or pin a callback port anywhere: the server supports OAuth Dynamic Client Registration, so Claude Code registers its own client on an ephemeral loopback port.
Step 4: run `claude mcp list`. Expect either `plugin:outsystems:outsystems: https://<my-tenant>/mcp`, or, if I installed before 0.20.0, only `outsystems: https://<my-tenant>/mcp`: that is an older entry hiding the plugin's server as a duplicate. In the second case, or if both appear with different URLs, run `claude mcp get outsystems` to read its `Scope` and `URL`, tell me both, and, unless that scope is `project` (shared config: report it and let me decide), ask before running `claude mcp remove outsystems -s <that scope>`; then re-run `claude mcp list` and confirm `plugin:outsystems:outsystems` now appears. If the list shows no `outsystems` line at all, the tenant option was not stored: re-run Step 3.
Step 5: tell me to restart Claude Code, then ask anything OutSystems-related; you'll drive the OAuth flow automatically via Claude Code's synthesized `authenticate` tool (a client convenience, not a server tool). If that doesn't trigger, or a call fails with an auth error, tell me to open `/mcp`, pick the `outsystems` server marked as coming from the plugin, and choose Authenticate as the fallback.

Update: run claude plugin marketplace update outsystems, then claude plugin update outsystems@outsystems, then restart Claude Code. The first command refreshes Claude Code's cached copy of this repo's marketplace; the second compares the installed plugin version with it and installs the newer plugin, or reports already at the latest version. Run both, in this order: the second alone compares against the stale cache and reports the old version as the latest, and the first alone leaves the installed plugin as it was. The update refreshes the skill however the MCP server is registered, including an older claude mcp add entry.

Upgrading from a version before 0.20.0? The old recipe registered the server with claude mcp add at user scope. That entry keeps working, and when it points at the same tenant Claude Code keeps it and hides the plugin's server as a duplicate. To move to the plugin's server: set the option with claude plugin install outsystems@outsystems --config tenant_hostname=<my-tenant> (bare hostname, no scheme prefix, no path; on an installed plugin this only updates the option), remove the old entry with claude mcp remove outsystems -s user, and restart Claude Code. Removing the entry also drops its saved sign-in, so expect one sign-in on your next OutSystems request. The plugin's tools are named mcp__plugin_outsystems_outsystems__<tool>, so rename any permission rules or hooks you wrote against mcp__outsystems__<tool>.

After install, you can also type /outsystems-feedback <message> in Claude Code to send feedback about the agent experience so the maintainers can act on it. The slash command is Claude-Code-only (and uses the outsystems- prefix so it doesn't collide with Claude Code's built-in /feedback, which routes to Anthropic's issue tracker); on other harnesses, ask the agent in plain language ("send a thumbs-up about the OutSystems agent") and it will invoke the underlying feedback tool.

Install - Claude Desktop

Use the local proxy below. Claude Desktop's native Add custom connector flow always fails during OAuth sign-in against any OutSystems tenant: the connector's claude.ai callback URL is rejected, because the tenant's identity provider accepts only loopback redirect URIs. It is not a working install path; the native steps are kept in the collapsed section below for reference only.

MCP server: paste into Claude Desktop (requires Node.js with npx available on your machine):

Install the OutSystems MCP server in Claude Desktop via a local proxy.
Step 1: confirm Node.js is available (`npx --version`). If it isn't, stop and tell me to install Node.js first — writing the config below without it produces a server that silently fails to connect. Then install `mcp-remote` globally at the pinned version: `npm install -g mcp-remote@0.14.3` (idempotent, safe if already installed). Use exactly this version, never `@latest` or an unversioned name: releases 0.9.0 through 0.13.5 fail every sign-in with `IssuerMismatchError`.
Step 2: ask me for my OutSystems tenant hostname (something like `mycompany.outsystems.dev`). Strip any scheme, leading `www.`, trailing slash, and path or query, keeping only the host. If the result doesn't match `^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$`, ask again rather than proceeding with an unvalidated value.
Step 3: locate the Claude Desktop config file, `claude_desktop_config.json`: on macOS it is in `Library/Application Support/Claude` under my home folder, on Windows in the `Claude` folder of my roaming AppData directory, on Linux in `.config/Claude` under my home folder. Read the file (start from `{}` if it doesn't exist). Preserve every existing key — other entries belong to other MCP servers and may hold private values, so don't paste the full file contents back to me; quote only the `outsystems` entry you're adding or changing. Patch the top-level `mcpServers` object by adding or replacing the `outsystems` entry:
  - macOS/Linux: `{"command": "npx", "args": ["mcp-remote@0.14.3", "https://<my-tenant>/mcp"]}`
  - Windows: `{"command": "cmd", "args": ["/c", "npx mcp-remote@0.14.3 https://<my-tenant>/mcp"]}` (safe here because Step 2 already restricted the tenant hostname to the pattern above, so it can't break out of this shell string)
Substitute my actual tenant hostname for `<my-tenant>`. Write the file back.
Step 4: tell me to restart Claude Desktop.
Step 5: After restarting, if the server fails to connect: Claude Desktop launches processes with a minimal PATH, and a broken, stale, or mistyped `"command"` value looks identical to Desktop. macOS/Linux, replace whatever the `"command"` value currently is with the full path from `which npx`. Windows, if the `"command"` value is anything other than `"cmd"`, restore it to `"cmd"` first; then replace whatever text stands in for `npx` inside the `/c` argument string with the `.cmd` path from `where npx` (the line ending in `.cmd`), quoting it if it contains a space — it commonly does (e.g. `C:\Program Files\nodejs\npx.cmd`). Restart Claude Desktop again and retry; if it still doesn't connect after that, stop and point me at https://github.com/OutSystems/outsystems-mcp#troubleshooting rather than continuing to guess. Otherwise, the first OutSystems tool call will open a browser window for OAuth sign-in; complete the sign-in when prompted.

Skill: once the MCP server is wired up above, install the plugin too: it delivers the skill.

Requires a paid plan: Plugins require a paid plan (Pro, Max, Team, Enterprise), and Enterprise admins may restrict which plugins install.

Add the OutSystems/outsystems-mcp marketplace and install the outsystems plugin from Claude Desktop's plugin install flow, the same marketplace and plugin the Claude Code recipe above uses, then restart Claude Desktop.

The plugin also declares the same server for Claude Code, built from a tenant_hostname plugin option. Desktop's Chat tab keeps using the local-proxy entry you just wrote, and the Code tab loads that same entry from claude_desktop_config.json, so both work with the option unset. We have not verified whether Desktop asks for the option when you install the plugin, nor whether it loads the plugin's server at all. Set the option only if you also want the plugin's own HTTP server; if the Code tab does load it, expect two outsystems servers there. Setting it needs the standalone claude CLI in a terminal: claude plugin install outsystems@outsystems --config tenant_hostname=<my-tenant> (bare hostname, no scheme prefix, no path).

<details> <summary>Native "Add custom connector" steps (not currently working, kept for reference)</summary>

1. Open Settings > Connectors.
2. Click Add custom connector.
3. Enter https://<my-tenant>/mcp, substituting your OutSystems tenant hostname (something like mycompany.outsystems.dev).
4. Click Add. The first OutSystems tool call opens a browser for OAuth sign-in, which always fails against any OutSystems tenant today; use the local-proxy steps above instead.

Available on Free, Pro, Max, Team and Enterprise, with Free limited to one custom connector. A custom connector is also reached from Anthropic's cloud rather than from your machine, so it cannot reach a tenant that is VPN-only or IP-allowlisted; the local proxy is required there too.

If the flow starts working: on a Team or Enterprise plan you may not see "Add custom connector" at all, because adding custom connectors is an organization-level permission. An Owner adds the connector in Admin settings > Connectors and members then click Connect on it. If your organization has custom connectors disabled entirely, no member can add one and neither can an Owner without changing that policy.

</details>

Note: the plugin installed abo