midPoint MCP Server

midpoint-mcp-server connects AI assistants to Evolveum midPoint through the Model Context Protocol (MCP). It gives an assistant 39 tools to look up users, roles and resources, request roles, decide approvals, see a manager's team, check what failed recently and, when you allow it, change midPoint. Every call goes through midPoint's REST API as a real midPoint user, so midPoint's own authorizations, approval policies and audit trail apply to it. It is written for midPoint administrators who want to offer an assistant to their users or use one themselves. It ships as one static Go binary and supports midPoint 4.10 (see midPoint versions).

Try the demo: strazahq.github.io/midpoint-mcp-server shows the four interactive views (approval inbox, Get access, My requests, My team's access) in a simulated chat with sample data, including the "allow this tool?" step. It is built from this repository by node demo/build.mjs.

Choose how to run it

The server has two modes. The mode decides which midPoint user each call runs as.

Personal mode is the default. You run the server on your own machine, your MCP client starts it over stdio, and it signs in to midPoint with your own credentials. midPoint sees you because the server signs in as you. No identity provider is involved.

Shared mode serves many people from one server over HTTP. Each request carries an OpenID Connect (OIDC) access token. The server validates the token, finds the matching midPoint user and runs the call as that user through a service account. midPoint sees the real person behind every request.

Shared mode needs both the issuer and audience settings and the --http flag. Over stdio the server always runs in personal mode, and without the two OIDC settings the token code never runs.

Personal mode assumes the credentials belong to the person using the assistant. If you run it with a shared technical account instead, for example when a gateway starts one server process per session, midPoint answers for that account. Tools such as list_my_team and list_work_items then describe the account, not the person reading the answer. The whoami tool always says which identity the server acts as. Set identity.credentialIsShared in the settings file to make the self-scoped tools refuse instead of answering. Shared mode is the real fix, because each request then carries the caller's own identity.

Related MCP server: @godrix/argocd-mcp

Get started

In the examples below, replace the example.com addresses and every value in angle brackets, such as <service-account-password>, with your own.

Get the binary

Download the archive for your platform from this repository's GitHub releases. Releases are built for Linux and macOS on amd64 and arm64, and for Windows on amd64. Check a release lists the files a release carries and shows how to verify them. To build it yourself you need Go 1.25 or later:

CGO_ENABLED=0 go build -o midpoint-mcp-server .

midpoint-mcp-server --version prints the version, as Versions explains.

Check a release

Each release carries these files, where <tag> is the release tag, such as v1.2.3:

• midpoint-mcp-server_<tag>_<os>_<arch>.tar.gz for linux and darwin on amd64 and arm64, and midpoint-mcp-server_<tag>_windows_amd64.zip. Each archive holds the binary, README.md, LICENSE and CHANGELOG.md.

• SPDX SBOMs in JSON: midpoint-mcp-server_<tag>_binaries.spdx.json for the binaries, and midpoint-mcp-server_<tag>_image_linux_amd64.spdx.json and midpoint-mcp-server_<tag>_image_linux_arm64.spdx.json for the container image.

• midpoint-mcp-server-kubernetes.yaml, the manifests from deploy/kubernetes with the image pinned to the release's version.

• checksums.txt, the SHA-256 sum of each file above, and checksums.txt.sigstore.json, its signature bundle.

The release workflow signs checksums.txt and the container image with cosign's keyless signing, so no key is published. The signing certificate names this repository's release workflow and the tag it ran for. Verify the signatures with cosign 3 or later. For the downloads, run this in the directory that holds them:

cosign verify-blob checksums.txt \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp '^https://github\.com/Strazahq/midpoint-mcp-server/\.github/workflows/release\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
sha256sum --ignore-missing -c checksums.txt

For the image, where <version> is the release version without its v, such as 1.2.3:

cosign verify ghcr.io/strazahq/midpoint-mcp-server:<version> \
  --certificate-identity-regexp '^https://github\.com/Strazahq/midpoint-mcp-server/\.github/workflows/release\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

GitHub also holds a build provenance attestation for each archive, each binary and the image. gh attestation verify <file> --repo strazahq/midpoint-mcp-server checks one file, and the same command with oci://ghcr.io/strazahq/midpoint-mcp-server:<version> in place of the file checks the image.

Personal mode in three steps

1. Add the server to your MCP client. For Claude Desktop, put this in claude_desktop_config.json:

   {
     "mcpServers": {
       "midpoint": {
         "command": "<install-dir>/midpoint-mcp-server",
         "env": {
           "MIDPOINT_URL": "https://midpoint.example.com/midpoint",
           "MIDPOINT_USERNAME": "<your-midpoint-login>",
           "MIDPOINT_PASSWORD": "<your-midpoint-password>"
         }
       }
     }
   }

2. Restart the client.

3. Ask the assistant to run the whoami tool. It answers with your midPoint login and says personal mode.

The write tools only return a dry-run preview until you add "MIDPOINT_MCP_ALLOW_WRITES": "true" to env. The client's configuration file now holds your password, so keep it private.

Shared mode in five steps

Read docs/misconfigurations.md before you start the server in step 4. It lists the configuration mistakes that let one person act as another in midPoint.

1. In your identity provider, make the access tokens meant for this server carry an audience (aud) of your choice, for example midpoint-mcp. docs/identity-providers.md shows how for common providers. examples/keycloak.env and examples/entra.env are annotated starting points.

2. In midPoint, create a service account for the server. Give it a role based on examples/role-mcp-rs-service.xml, after replacing its placeholder archetype oids with the archetypes of the users it may act for, in both places it lists them. The server also looks users up as this account, so the role carries one read authorization, limited to those archetypes and the items the server matches on. Add your correlation attribute to it if that is not name. Apart from that read, the role holds only REST entry actions and #proxy: every tool call runs on the person's own midPoint rights. docs/authorization.md explains each grant. Run the correlation check in Verify a deployment after importing.

3. Make sure every person matches exactly one midPoint user. With the default settings, the token's preferred_username must equal the user's name. The server first tries the token's sub against a user item called externalId, but midPoint 4.10's standard user schema has no such item, so on a stock deployment that first search never matches. Each person also needs midPoint authorizations of their own, such as the built-in End user role, because every call runs as them.

4. Start the server:

   export MIDPOINT_URL=https://midpoint.example.com/midpoint
   export MIDPOINT_USERNAME=mcp-service
   export MIDPOINT_PASSWORD='<service-account-password>'
   export MIDPOINT_MCP_OIDC_ISSUER=https://idp.example.com/realms/corp
   export MIDPOINT_MCP_OIDC_AUDIENCE=midpoint-mcp
   midpoint-mcp-server --http 0.0.0.0:3001

   This minimal example keeps the default correlation, which fits people in the Keycloak setup in docs/identity-providers.md. On Microsoft Entra ID the default claim is unsafe, so use the settings in examples/entra.env instead. The startup log line says resource-server mode (OIDC bearer).

5. Check it. curl -i -X POST http://localhost:3001/mcp must answer 401, because it carries no token. Then put a TLS-terminating proxy in front of the server, as HTTP transport explains, connect your MCP client or gateway to the proxy's https:// address for /mcp with a person's access token, and call whoami. It names that person and says resource-server mode.

The client or gateway in front of the server gets the access token from your identity provider and sends it as Authorization: Bearer <token> on every request. The server only validates tokens, so it needs no client secret. It does not publish OAuth protected-resource metadata, so it cannot point a client to the identity provider by itself.

Understand how shared mode decides who is calling

On every HTTP request, shared mode answers four questions in order. A request that fails one of the first three gets HTTP 401 and never reaches a tool. No tool argument can change who the caller is.

1. Is the token signed by the identity provider you trust? At startup the server reads the provider's discovery document for MIDPOINT_MCP_OIDC_ISSUER, and it refuses to start if it cannot. On each request it checks the token's signature against the provider's published keys, checks that the iss claim equals the configured issuer exactly, and checks that the token has not expired. Only asymmetric signatures (RSA, ECDSA, RSA-PSS and EdDSA) are accepted, and a token without an expiry is refused.

2. Was the token issued for this server? Its aud claim must contain MIDPOINT_MCP_OIDC_AUDIENCE. A valid token that the provider issued for another application fails here.

3. Which midPoint user is it? The server first looks for a user whose externalId equals the token's sub. midPoint 4.10's standard user schema has no externalId item, so on a stock deployment this search fails and the server moves on without reporting it. If the first search fails or finds no single user, the server looks for a user whose correlation attribute (name by default) equals the token's correlation claim (preferred_username by default). If neither lookup finds exactly one user, the request is refused. The lookup runs as the service account, without impersonation, so that account needs read access to the users it may match. Tokens that an agent or a service obtains for itself follow a stricter path, set up with the two MIDPOINT_MCP_OIDC_CLIENT_* settings.

4. What may that user do? The server calls midPoint as the service account and adds the header Switch-To-Principal: <user-oid>, so midPoint runs the call as the matched user. midPoint decides with its own authorizations. The service account needs REST access to the endpoints the tools use and the #proxy authorization, scoped to the users it may act for. The user needs the authorizations for the operation itself. The server grants nothing of its own, and midPoint's approvals and audit records name the real person.

docs/identity-providers.md covers provider setup, correlation and agent tokens in depth. docs/authorization.md covers the service account's role and the reason for each grant. docs/misconfigurations.md lists the configuration mistakes that break security and how to spot them.

Configure the server

All settings are environment variables, plus one optional settings file. Credentials are read from the environment only, and the server never writes them to disk, logs or tool output. A true/false setting is on only when its value is true, in any letter case.

Settings for both modes

Settings for shared mode

The server refuses to start, with a message that names the setting to fix, when:

• a required variable is missing,

• only one of the issuer and the audience is set,

• only one of the two MIDPOINT_MCP_OIDC_CLIENT_* settings is set,

• the discovery URL is set without the issuer, carries a user name or password, or is not an absolute http or https URL,

• the correlation attribute or an archetype oid holds characters that are not safe in a midPoint query,

• the settings file cannot be read or fails validation.

The settings file

MIDPOINT_MCP_CONFIG points at a JSON file of non-secret settings for things the server cannot guess, such as how your deployment models org structure. Credentials are never read from it. Every key is optional. Keys that start with // are comments and are ignored. Any other unknown key stops the server at startup, so a typo cannot silently keep a default. examples/midpoint-mcp.config.json is an annotated copy with every default.

Request fields

There are no field settings. A request offers every field midPoint's own Request access page would: the assignment extension items of midPoint's schema. The server reads them once at startup, as its own account and without impersonation, from GET /ws/rest/schemas and GET /ws/schema, together with the lookup tables their choice lists name. It needs model read on SchemaType and LookupTableType, model-3#getExtensionSchema, and the REST actions getObjects and getExtensionSchema; examples/role-mcp-rs-service.xml has them. Without them the server starts with a warning and requests carry no fields. Restart the server after a schema change.

• Types. Text, yes/no, whole and decimal numbers, dates, dates with a time, choice lists (an enumeration or a lookup table), and fields with several values. A reference or a structured value can't be filled here; the dialog says midPoint's own page also asks for it.

• Required. The schema's minOccurs marks a field required, as on midPoint's page. midPoint itself doesn't check it, so the server does.

• Who must fill what is midPoint's call. midPoint checks a request against the person's authorizations and its policy rules on Send, the same as for its own page. When it refuses, the person sees midPoint's reason, such as a policy rule's own message.

• Approvers see every field a request carries, labelled, and the comment typed in midPoint's own page when midPoint lets them read the case's events.

What midPoint's REST API can't do, so this server doesn't either: tell which fields a particular person may fill before Send, offer a relation other than member, preview conflicting roles before Send, or carry the comment of midPoint's own Request access page. midPoint still enforces all of these on Send.

requests.formItems and requests.justificationItem from 0.5 are ignored, with a warning.

The request access preview

midPoint can let each person request different roles, for different people, with different relations and fields. Its own Request access page asks midPoint internally; REST can't ask. So the server works it out from the same source: the request rules (#assign authorizations) of the roles the person holds.

1. It reads the person's record, as the person, for their memberships.

2. It reads those roles' rules as the server's own account, which needs one narrow read: name, displayName, authorization, lifecycleState, activation and delegable of roles, orgs, services and archetypes (examples/role-mcp-rs-service.xml, "read-request-rules"). Definitions, not people's data. Nothing is cached.

3. It asks midPoint, as the person, which roles and people each rule names.

4. It offers a role when a rule allows it and none denies it, and names those rules ("End user › assign-requestable-roles"), so anyone can check the offer against midPoint's configuration.

Relations other than member are offered only where a rule names them; a rule without a relation means member here, as on midPoint's page, although midPoint's server would accept any. Where the server can't evaluate a rule exactly (a script in a filter, an unusual selector), it shows more and says so; midPoint decides on submit, as always. Without the grant, or in personal mode, the dialog lists the roles flagged requestable, as before.

Know the limits and risks

• People can see more here than in midPoint's own pages. The server is a REST client. It shows what midPoint's model and REST permissions allow, and nothing that only midPoint's pages apply. If a deployment hides an item or a panel only in the GUI, for example with UI authorizations (authorization-ui-3), adminGuiConfiguration visibility, or Request access settings, while the person may still read it through the model, this server shows it. Any other REST client can read it too. Hiding something in the GUI is not a security boundary. To keep something from a person, take away the model permission.

• midPoint is the only enforcer. The server never grants anything itself. Every change is a plain REST request as the person, and midPoint applies that person's authorizations and its policy rules. A view can therefore offer something midPoint then refuses. When it does, the person sees midPoint's reason.

• REST can't do everything midPoint's own Request access page does. It can't say beforehand which fields a person may fill. It can't preview conflicting roles, and it can't carry the request comment. See Request fields.

• The server checks required request fields; midPoint doesn't. midPoint leaves required assignment fields unchecked on the server. A REST client other than this one can leave them empty.

• In shared mode the service account is the blast radius. Anyone holding its credentials can act as every person inside its #proxy scope. Keep that scope narrow, and keep the account's own rights to what docs/authorization.md lists.

• Text from midPoint is written by other people. Descriptions, comments, request fields and midPoint's refusal messages reach the assistant marked as untrusted, but a model can still be swayed by them. Leave writes off (MIDPOINT_MCP_ALLOW_WRITES unset) unless people confirm each write in their assistant app, which MCP hosts ask for by default.

• midPoint 4.10 only, see midPoint versions.

Connect a client or run it in a container

VS Code

Claude Desktop is shown in Personal mode in three steps. VS Code uses the same shape in .vscode/mcp.json or your user-level mcp.json. Keep a file that holds a password out of version control.

{
  "servers": {
    "midpoint": {
      "command": "<install-dir>/midpoint-mcp-server",
      "env": {
        "MIDPOINT_URL": "https://midpoint.example.com/midpoint",
        "MIDPOINT_USERNAME": "<your-midpoint-login>",
        "MIDPOINT_PASSWORD": "<your-midpoint-password>"
      }
    }
  }
}

Docker

Each release publishes an image for linux/amd64 and linux/arm64 as ghcr.io/strazahq/midpoint-mcp-server. Its tags are the release version without the v, such as 1.2.3, the minor version, such as 1.2, and latest. Check a release shows how to verify its signature. To build the image yourself instead:

docker build -t midpoint-mcp-server .

The image is scratch with only the static binary and CA certificates, and it runs as the unprivileged user 65534. A -e NAME with no value passes that variable from your shell, which keeps the password off the command line. The examples below use the published image, where <version> is a release version such as 1.2.3. For an image you built yourself, use midpoint-mcp-server in its place.

Personal mode over stdio needs -i to keep stdin open:

docker run --rm -i \
  -e MIDPOINT_URL=https://midpoint.example.com/midpoint \
  -e MIDPOINT_USERNAME \
  -e MIDPOINT_PASSWORD \
  ghcr.io/strazahq/midpoint-mcp-server:<version>

Shared mode over HTTP passes the flags after the image name:

docker run --rm -p 3001:3001 \
  -e MIDPOINT_URL=https://midpoint.example.com/midpoint \
  -e MIDPOINT_USERNAME \
  -e MIDPOINT_PASSWORD \
  -e MIDPOINT_MCP_OIDC_ISSUER=https://idp.example.com/realms/corp \
  -e MIDPOINT_MCP_OIDC_AUDIENCE=midpoint-mcp \
  ghcr.io/strazahq/midpoint-mcp-server:<version> --http 0.0.0.0:3001

If the container reaches the identity provider under another host name than the issuer in the tokens, set MIDPOINT_MCP_OIDC_DISCOVERY_URL to the discovery document's address on that network. To use a settings file, mount it and point MIDPOINT_MCP_CONFIG at it, for example -v "$PWD/midpoint-mcp.config.json:/config.json:ro" -e MIDPOINT_MCP_CONFIG=/config.json. The file must be readable by user 65534. Personal mode over HTTP can only bind a loopback address, so inside a container it needs host networking (--network host).

Kubernetes

deploy/kubernetes/README.md runs shared mode on Kubernetes with plain manifests. They run one hardened replica that reads its settings from a Secret named midpoint-mcp-server, which you create, and include an example Ingress that terminates TLS. Each release also attaches midpoint-mcp-server-kubernetes.yaml, the same manifests with the image pinned to that release's version.

HTTP transport

--http <address> serves the streamable HTTP transport at the path /mcp instead of stdio:

midpoint-mcp-server --http :3001   # serves http://127.0.0.1:3001/mcp

An address without a host binds 127.0.0.1, and a bare port such as 3001 works too. In personal mode the server refuses to start on an address that is not a loopback address or localhost. Without per-request authentication, anyone who reached it would act as the configured login, and no flag overrides this. In shared mode every request needs a valid token, so any address is allowed.

The server speaks plain HTTP and has no TLS settings. Put a TLS-terminating proxy in front of it whenever it listens beyond the local machine, so access tokens never travel in clear text.

Let a gateway list tools before sign-in

Some gateways and catalogs list a server's tools before any user has signed in. In shared mode that request normally gets 401. Setting MIDPOINT_MCP_ANONYMOUS_DISCOVERY=true lets a caller without a token use exactly these methods: initialize, notifications/initialized, ping, tools/list, resources/list, and resources/read for a ui://midpoint/ address.

A tokenless caller gets only static content: tool names, descriptions, input schemas and the view templates, the same for everyone. None of these methods reaches midPoint. These rules apply:

• A request with any Authorization header is always verified, whatever it asks for. Verification is what binds a session to a user.

• A JSON-RPC batch goes without a token only when every message in it is one of the methods above. One tools/call in the batch makes the whole request need a token.

• A body that does not parse, or is larger than 64 KiB, needs a token.

• A session opened without a token still accepts a later tools/call with a token, and that call runs as the token's user.

• The ping method above is the protocol ping. The ping tool, which calls midPoint, is reached through tools/call and needs a token.

The setting is off by default and does nothing outside shared mode. When it is on, the startup log line says anonymous discovery ON. It is the only part of the server that a network caller can reach without a token, so turn it on only when a gateway needs it.

Use the interactive views

Hosts that render MCP Apps views get four interactive screens, embedded in the binary. docs/ui-contract.md specifies them.

A session counts as a UI session when its client advertises the io.modelcontextprotocol/ui extension with the text/html;profile=mcp-app MIME type. Only a UI session sees _meta.ui on tools and the ui://midpoint/* resources in resources/list. In a UI session, tools that no view uses are marked as visible to the model only. Any other session's tool list is unchanged. A view document can be read in any session.

The results of the twelve tools that views render or call carry three fields in every session: tool, acting, which is the identity midPoint ran the call as, and server, which reports the write gate, features and versions. They are the ten tools in the table above, plus list_my_managers and whoami.

Find the right tool

Every tool runs as the identity described in Choose how to run it, so midPoint only returns and changes what that identity may see and change. Tools marked "Write gate" return a dry-run preview of the exact request until MIDPOINT_MCP_ALLOW_WRITES=true. The other tools only read. List tools return 20 results by default and at most 100.

Identity

Users, roles and resources

Requests and approvals

Managers and teams

Team results name the identity they answered for and the org links they used, so an empty result shows why it is empty. The team.* keys of the settings file decide which org links count. A manager who is not a superuser sees reports only with a read authorization over them, because being an org manager does not grant it. midPoint's usual answer is an authorization whose object selector uses orgRelation with subjectRelation set to the manager relation.

Reports

Administration

Every write tool takes the midPoint name of the user and role it changes (userName, roleName) next to their OIDs, so an app that asks you to allow the call shows names you can check. The server refuses a name that doesn't match its OID before writing.

Tasks and systems

Build and test

• go test ./... runs the unit tests against recorded REST responses. It needs no midPoint.

• go test -tags=integration ./... adds live tests against a real midPoint, such as a 4.10 container. They read the MIDPOINT_* variables and skip when those are unset.

• node test/views/run.mjs checks a view document in headless Chromium. It needs Node 18 or later and Playwright, as test/views/README.md explains.

• CI runs gofmt, go vet and the unit tests on pushes to main and on pull requests. When deploy/kubernetes changes, another workflow renders the manifests and validates them with kubeconform. Pushing a tag such as v1.2.3 runs the same checks and publishes the release described in Check a release. The release is refused unless CHANGELOG.md has a non-empty section headed ## [1.2.3], and that section becomes the release notes.

midPoint versions

The server supports midPoint 4.10. Every live check in this repository, and every [live] note in the docs, was made against midPoint 4.10.3. Other versions are not tested and may not work, even partly:

• 4.8 and 4.9: older layouts of what the server reads. Value metadata (@metadata) on assignments, role memberships and cases holds where an assignment came from and which role grants another. The server falls back to the older metadata container for creation times and assignment origin, but "comes with …" needs the 4.10 layout. Approval cases (stages, approvers, work items offered to a group), the query language the searches use, the REST actions it relies on (Switch-To-Principal with archetype-scoped #proxy, claim, release, cancel, task and resource actions) and the audit script route may also differ.

• 4.11 and later: not released or not yet tried. The same areas are the ones to check first.

Before you run another version, run go test ./..., then the live checks in docs/authorization.md against a test midPoint of that version. Report what differs in an issue.

Versions

The server's own version is its git tag, written vMAJOR.MINOR.PATCH, and it follows semantic versioning. --version prints it, and the server reports it to MCP clients as its version in the initialize result and in the server field of the view tools' results. A binary built from source without the release's build flags reports 0.0.1-dev, and an image built without --build-arg VERSION=<tag> reports docker. Image tags leave out the v, so release v1.2.3 is the image tag 1.2.3.

The MCP protocol revision is separate from the server's version. It is named by a date, such as 2025-06-18, and the official MCP Go SDK negotiates it with each client during initialize. The server uses go-sdk v1.6.1, which supports the revisions from 2024-11-05 to 2025-11-25. It answers with the client's revision when it supports that one, and with 2025-11-25 otherwise.

License

Apache-2.0. See LICENSE.