MCP Access

Connect agents to MEMIS

This project exposes a delegated-user MCP server for EMIS data. Humans can use this page to configure Keycloak and MCP clients. Agents can also read this page to discover the correct endpoints, auth model, and requested scopes.

Endpoints

MCP

https://www.memis-agent.online/api/mcp

Protected Resource Metadata

https://www.memis-agent.online/.well-known/oauth-protected-resource/api/mcp

Authorization Server Metadata

https://www.memis-agent.online/.well-known/oauth-authorization-server

Auth model

  • Delegated real-user access only
  • Authorization code + PKCE against EMIS Keycloak
  • MCP resource server is this app, not Keycloak
  • Final RBAC enforcement still happens in MVP2 backend
  • OpenClaw should keep tokens outside mcp.servers.*.oauth
  • Hermes may need explicit client metadata and non-redirecting canonical URLs

Client compatibility notes

OpenClaw

Verified working. Best path is minimal saved MCP config plus a separate openclaw mcp login OAuth flow.

Hermes

More fragile. Prefer canonical www URLs, explicit client_id, and direct authorization metadata. Do not assume dynamic client registration. For this installed Hermes CLI, use hermes mcp test memis-mcp for validation rather than nonexistent tools or call subcommands.

Generic MCP clients

Start with protected-resource discovery first. If discovery is weak, fall back to explicit issuer, client_id, scopes, and auth metadata.

Prompt for OpenClaw

Optimized for OpenClaw's built-in MCP commands and external OAuth token store.

Connect to the MEMIS MCP server for me using OpenClaw.

Use this MCP resource:
- https://www.memis-agent.online/api/mcp

OAuth discovery:
- Protected resource metadata: https://www.memis-agent.online/.well-known/oauth-protected-resource/api/mcp
- Authorization server metadata: https://www.memis-agent.online/.well-known/oauth-authorization-server

Use delegated user login with OAuth2 authorization code + PKCE (S256).
Do not use a robot account or service account.

If your MCP client supports protected-resource discovery, start from the MCP URL or the protected resource metadata URL and follow the authentication challenge automatically.

If OpenClaw needs explicit OAuth settings, use:
- issuer: https://sso.memis.online/realms/emis2
- client_id: emis-app-mcp-native
- scopes: openid profile email emis:institution:read emis:student:read emis:hr:read emis:curriculum:read emis:workflow:read

Important:
- Do not write access tokens, refresh tokens, code verifiers, issuer, or client_id back into OpenClaw's mcp.servers.*.oauth config block.
- For OpenClaw, save only the MCP URL, transport, auth: "oauth", and oauth.scope in config, then let `openclaw mcp login` store OAuth state separately.

After connecting, verify the MCP server by:
1. listing tools
2. calling get_access_context
3. if available, calling search_institutions

If login is required, open the browser and let me authenticate as the current EMIS user.

Prompt for Hermes

More explicit for Hermes, which may need canonical www URLs, fixed client_id, and direct auth metadata.

Connect to the MEMIS MCP server for me using Hermes agent.

Use the canonical hosted URLs below exactly as written:
- MCP resource: https://www.memis-agent.online/api/mcp
- Protected resource metadata: https://www.memis-agent.online/.well-known/oauth-protected-resource/api/mcp
- Authorization server metadata: https://www.memis-agent.online/.well-known/oauth-authorization-server

Use delegated user login with OAuth2 authorization code + PKCE (S256).
Do not use a robot account or service account.

Important Hermes compatibility notes:
- Do not rely on dynamic client registration. Use the explicit client_id: emis-app-mcp-native.
- Prefer the canonical www URLs above so Hermes does not get stuck on apex-to-www redirects.
- If Hermes supports explicit auth metadata better than protected-resource discovery, use the authorization server metadata URL above directly.
- Requested scopes: openid profile email emis:institution:read emis:student:read emis:hr:read emis:curriculum:read emis:workflow:read

If Hermes needs an explicit config block, use a shape like:

```yaml
mcp_servers:
  memis-mcp:
    url: "https://www.memis-agent.online/api/mcp"
    auth: oauth
    oauth:
      client_id: "emis-app-mcp-native"
      issuer: "https://sso.memis.online/realms/emis2"
      oauth_metadata_url: "https://www.memis-agent.online/.well-known/oauth-authorization-server"
      scope: "openid profile email emis:institution:read emis:student:read emis:hr:read emis:curriculum:read emis:workflow:read"
      redirect_port: 0
```

After connecting, verify:
1. run `hermes mcp test memis-mcp`
2. confirm the saved config still points to:
   - url: https://www.memis-agent.online/api/mcp
   - issuer: https://sso.memis.online/realms/emis2
   - oauth_metadata_url: https://www.memis-agent.online/.well-known/oauth-authorization-server
3. confirm OAuth token files exist under:
   - C:\Users\Dell Pro PA1420\AppData\Local\hermes\mcp-tokens\memis-mcp.json
   - C:\Users\Dell Pro PA1420\AppData\Local\hermes\mcp-tokens\memis-mcp.meta.json
4. if interactive tool inspection is available inside Hermes, list tools
5. call get_access_context
6. if available, call search_institutions

If login is required, open the browser and let me authenticate as the current EMIS user.

Hermes quick test

After login succeeds, a human can verify the Hermes connection locally with the commands below.

hermes mcp test memis-mcp
Get-ChildItem C:\Users\Dell Pro PA1420\AppData\Local\hermes\mcp-tokens
Get-Content C:\Users\Dell Pro PA1420\AppData\Local\hermes\config.yaml
A healthy result should show:
  • Connected over HTTP to https://www.memis-agent.online/api/mcp
  • Auth: OAuth 2.1 PKCE
  • Tools discovered: 9
  • token files such as memis-mcp.json under mcp-tokens

What success looks like

Your current Hermes test is already in the good state:

Testing 'memis-mcp'...
Transport: HTTP → https://www.memis-agent.online/api/mcp
Auth: OAuth 2.1 PKCE
✓ Connected
✓ Tools discovered: 9

Keycloak client

Create a separate native/public OIDC client such as emis-app-mcp-native.

Recommended settings:

  • Client authentication: Off
  • Standard flow: On
  • Direct access grants: Off
  • PKCE: S256
  • Redirect URIs: http://127.0.0.1/*, http://localhost/*

Repo guide: external/emis-chatbot/admin_plans/mcp/keycloak_client_setup.md

Requested scopes

openidprofileemailemis:institution:reademis:student:reademis:hr:reademis:curriculum:reademis:workflow:read

OpenClaw-safe example

For OpenClaw, keep the saved MCP config minimal, then let openclaw mcp login manage PKCE state and tokens outside the config file.

openclaw mcp set memis-mcp '{"url":"https://www.memis-agent.online/api/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"openid profile email emis:institution:read emis:student:read emis:hr:read emis:curriculum:read emis:workflow:read"}}'
openclaw mcp login memis-mcp
Do not manually add accessToken, refreshToken, codeVerifier, issuer, or clientId under mcp.servers.*.oauth in ~/.openclaw/openclaw.json.