Skip to main content

AI native local MCP testing

Run Shellui shellui/dev next to the sibling service repos, then drive regional MCP with curl and a browser. Identity owns OAuth. The ai gateway owns tools/list, approvals, and session_allow. Use AI native MCP for short connector URL pointers. Links use the develop branch.

What this repo validates vs what you run locally​

What this repo validates:

  • pnpm run test:scripts runs python3 tools/test_generate_env.py.
  • When docker is installed, that script writes a temp env file and runs:
docker compose -f dev/docker-compose.yml \
--env-file <temp> config --format json

It checks resolved environment on identity, identity-global, ai, ai-global, and saas: JWT_ISSUER, regional GLOBAL_ISSUER_URL (identity-global, http://localhost:8007), saas GLOBAL_ISSUER_URL (http://localhost:8005), GLOBAL_AGENT_ISSUER_URL (ai-global, http://localhost:8008), GLOBAL_AGENT_LEGACY_ISSUER_URL, GLOBAL_AGENT_ACCESS_TOKEN_AUDIENCE, AI_SERVICE_ISSUER, AI_SERVICE_JWKS_URL, AI_SERVICE_MODE, regional IDENTITY_SERVICE_URL and IDENTITY_JWKS_URL (http://identity:8000), saas IDENTITY_INTERNAL_URL (http://identity-global:8000), AI_GLOBAL_ISSUER, REGION_CH_AI_URL, and a kid inside GLOBAL_JWKS. That is compose JSON. It does not send HTTP to the containers.

  • node scripts/verify-ai-native-doc.mjs
  • pnpm run docs:build

If docker is missing, the script prints docker not available; skipped compose config validation and pnpm run test:scripts still passes. Compose config assertions did not run on that host, not only the issuer checks. Those assertions also cover internal identity URLs and EMAIL_PUBLIC_URL on email and email-worker.

Live on your machine: with shellui/dev up, you run the regional OAuth steps below, tools/list on http://localhost:8006/c/1/mcp, human GET /api/v1/mcp/approvals, and POST /api/v1/mcp/approvals/{id}/decide. Activity is rendered by McpAgentActivitySection.tsx. That list loads tool calls from ai-service GET /ai/v1/mcp/personal/agents/{agent_id}/call-logs. Identity GET /api/v1/mcp/personal/agents/{id}/activity still returns OAuth consent (oauth.authorize.approved and oauth.device.approved). A 404 means you have no call logs for that agent. SaaS MCP is POST http://localhost:8005/mcp. Mint, exchange, gateway approval, and a downstream call are separate manual steps. This repo's pytest does not run that chain. Identity pytest covers exchange with fixtures. That is not this compose stack.

Global vs regional (no master token)​

  • Global MCP for a Shellui account is POST http://localhost:8008/mcp on ai-global (AI_SERVICE_MODE=global). Sign-in is identity-global. saas POST http://localhost:8005/mcp stays until cutover. Identity list_services still builds that saas URL from SAAS_SERVICE_URL plus /mcp. Regional identity personal status returns GLOBAL_MCP_URL (http://localhost:8008/mcp). An empty value falls back to {DASHBOARD_PUBLIC_URL}/mcp. It does not read regional identity, storage, hosting, or email data.
  • Regional gateway is POST http://localhost:8006/c/1/mcp for the seeded company (AI_SERVICE_MODE=region). The region service does not set SAAS_SERVICE_URL. POST http://localhost:8006/mcp returns 404 company_required.
  • A regional access token aud is that per-company URL. The global agent JWT aud is GLOBAL_AGENT_ACCESS_TOKEN_AUDIENCE (shellui_global_agent_dev in dev/.env.local.example), not http://localhost:8005/mcp and not http://localhost:8008/mcp. There is no master token.
  • Regional calls use a short-lived token from RFC 8693 exchange. Do not send the global JWT to a regional /mcp, and do not mint a stand-in with Django admin.
  • GET /api/v1/mcp/approvals and decide routes need a human company token, not an agent Bearer token.
  • GET /oauth/authorize on identity-global (http://localhost:8007) is user OpenID (scope openid email profile) with prompt=none. It is not the agent token endpoint.

Install and start (Shellui develop)​

Clone the repos side by side and start shellui/dev. See dev-stack. Then:

cd shellui/dev
./start.sh

start.sh runs generate-env.sh, then docker compose --env-file .env.local up --build. Identity publishes - '8001:8000'. Hosting publishes 8003:8000.

Set SHELLUI_INSTANCE_ROLE=region, GLOBAL_ISSUER_URL, GLOBAL_JWKS, GLOBAL_ACCESS_TOKEN_AUDIENCE, GLOBAL_AGENT_ISSUER_URL, GLOBAL_AGENT_JWKS, and GLOBAL_AGENT_ACCESS_TOKEN_AUDIENCE, or regional agent exchange returns 404. User exchange uses identity-global (http://localhost:8007). Agent exchange uses ai-global (http://localhost:8008). Until cutover it also accepts the saas origin (http://localhost:8005) from GLOBAL_AGENT_LEGACY_ISSUER_URL.

dev/generate_env.py builds GLOBAL_JWKS from the identity-global PEM, GLOBAL_AGENT_JWKS from GLOBAL_AGENT_SIGNING_KEY, and AI_GLOBAL_JWKS from AI_GLOBAL_SERVICE_SIGNING_KEY. GLOBAL_AGENT_KEY_ID is the kid in the legacy saas JWKS. dev/docker-compose.yml passes that saas PEM, the key id, and the audience into saas, and sets saas GLOBAL_ISSUER_URL to http://localhost:8005. Identity GLOBAL_AGENT_JWKS is AI_GLOBAL_JWKS. If you replace a PEM by hand, rerun generate-env.sh.

Human account and Terms before agent work​

seed_dev creates company 1 and a non-staff member dev@localhost. Request a magic link in the shell at http://localhost:4000, then open it from Mailpit at http://localhost:8025.

Accept Terms of Service on that human account before any agent step: register, authorize, token exchange, or tools/call. Staff accounts cannot authorize MCP clients. Sign in with dev@localhost.

Company id 1 is the seeded id (SHELL_IDENTITY_COMPANY_ID). The resource path below uses /c/1/mcp. If your membership is a different company, put that integer in the path.

Connect an agent from Settings​

Open Settings, then MCP / AI agents. Copy the company MCP URL on that page ({ai-service}/c/{company_id}/mcp, absolute) and the prompt next to it. The prompt tells the agent to add that URL as a remote MCP server and sign in with OAuth. It does not include an access token, a refresh token, a device code, or a user code.

What you do:

  1. Paste the prompt into your agent.
  2. Open the link it shows.
  3. Check the code and choose Allow.

A browser client opens the Identity consent page. A headless client or a command-line interface (CLI) uses device login. The agent calls POST /oauth/mcp/device/code with client_id and resource set to the company MCP URL. Identity returns a device code, a user code, and verification_uri ({identity}/oauth/mcp/device). The code expires in 600 seconds. The agent shows you the link and the code, then polls.

Open the link, sign in with a non-staff account, confirm the code, and choose Allow. Staff cannot approve. Identity then returns an access token that lasts 15 minutes and a refresh token bound to that MCP URL. The connection expires within 90 days.

The poll is POST /oauth/token. POST /oauth/mcp/token is the same handler. Send grant_type as the device-code grant:

urn:ietf:params:oauth:grant-type:device_code

Also send device_code, client_id, and resource set to the company MCP URL. authorization_pending means keep waiting. slow_down means wait longer than the current interval (it starts at 5 seconds). access_denied and expired_token stop the wait.

Return to the settings tab. The list reloads. A device-login row has kind oauth, plus the name, the created date, the expiry, and Revoke. Revoke is POST /api/v1/mcp/personal/agents/{id}/revoke.

Clients that only accept a static secret use the collapsed control on this page. Shellui shows that secret once. It is not part of the prompt. Creation still sends expires_at inside the 90-day cap (MCP_PERSONAL_AGENT_MAX_LIFETIME_DAYS).

ai-service must serve the protected-resource document for that URL:

GET /.well-known/oauth-protected-resource/c/{company_id}/mcp

The document lists resource, authorization_servers (the identity issuer only, equal to the issuer in identity metadata), scopes_supported of mcp, and bearer_methods_supported of header. A 401 from the company MCP URL sends WWW-Authenticate: Bearer with realm="mcp", resource_metadata set to that document, and scope="mcp". Do not put device_authorization_endpoint on that document. Identity's authorization-server metadata lists that endpoint and the device-code grant.

English prompt:

Connect to this Shellui company over MCP.

MCP URL: https://ai.example/c/1/mcp

Add this URL as a remote MCP server and sign in with OAuth.
If this client is headless or a CLI, use device login.
Show the link and the code, then wait until I approve them.

French prompt:

Connectez cette entreprise Shellui en MCP.

URL MCP : https://ai.example/c/1/mcp

Ajoutez cette URL comme serveur MCP distant et connectez-vous avec OAuth.
Si le client est sans interface ou en ligne de commande, utilisez device login.
Montrez le lien et le code, puis attendez que je les approuve.

Official MCP clients​

ai-service ./tools/mcp-e2e/run.sh starts identity, ai-service, Postgres, Redis, and a saas-mock. It runs the TypeScript MCP SDK, the Python mcp SDK, and @modelcontextprotocol/inspector --cli through registration, PKCE S256, POST /oauth/mcp/token, initialize, tools/list, and one harmless tools/call. That job clears storage, hosting, and email URLs. It is not shellui/dev. Shellui does not add a second Inspector script on the full stack. See ai-e2e.

Regional curl​

Use one loopback redirect in register, authorize, and token: http://127.0.0.1:8765/callback. Identity compares it to the registered list exactly. Start the listener before you open the authorize URL. It binds 127.0.0.1 port 8765, reads code from the query, and writes /tmp/shellui-mcp-code. Keep the same shell for the later blocks, or read those files.

Callback listener​

rm -f /tmp/shellui-mcp-code
python3 - <<'PY' &
from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.parse import parse_qs, urlparse
class H(BaseHTTPRequestHandler):
def do_GET(self):
q = parse_qs(urlparse(self.path).query)
code = (q.get("code") or [""])[0]
self.send_response(200)
self.send_header("Content-Type", "text/plain")
self.end_headers()
if not code:
self.wfile.write(b"no code\n")
return
open("/tmp/shellui-mcp-code", "w").write(code)
self.wfile.write(b"code saved\n")
self.server.stop = True
def log_message(self, *a):
return
s = HTTPServer(("127.0.0.1", 8765), H)
s.stop = False
while not s.stop:
s.handle_request()
PY

Register and save client_id​

POST /oauth/mcp/register returns 201 and client_id. The next block stores that id for the authorize URL and the token request.

python3 - <<'PY'
import json, urllib.request
body = json.dumps({
"client_name": "local_dev_agent",
"redirect_uris": ["http://127.0.0.1:8765/callback"],
}).encode()
req = urllib.request.Request(
"http://localhost:8001/oauth/mcp/register",
data=body,
headers={"Content-Type": "application/json"},
)
with urllib.request.urlopen(req) as res:
cid = json.load(res)["client_id"]
open("/tmp/shellui-mcp-client", "w").write(cid)
print(cid)
PY

PKCE and authorize URL​

GET /oauth/mcp/authorize reads response_type, client_id, redirect_uri, resource, code_challenge, and code_challenge_method (S256). It does not read scope or services. A repeated query key keeps the first value only. saas_offered=1 is the extra query ai-service adds when SAAS_SERVICE_URL is set. It does not grant SaaS by itself. The region ai service in this stack does not set SAAS_SERVICE_URL. urllib.parse.urlencode percent-encodes the query. Identity decodes it and matches redirect_uri to the registered string.

python3 - <<'PY'
import base64, hashlib, secrets
import urllib.parse as u
cid = open("/tmp/shellui-mcp-client").read().strip()
v = secrets.token_urlsafe(48)
raw = hashlib.sha256(v.encode()).digest()
c = base64.urlsafe_b64encode(raw).decode().rstrip("=")
open("/tmp/shellui-mcp-verifier", "w").write(v)
q = [
("response_type", "code"),
("client_id", cid),
("redirect_uri", "http://127.0.0.1:8765/callback"),
("resource", "http://localhost:8006/c/1/mcp"),
("code_challenge", c),
("code_challenge_method", "S256"),
("state", "local_dev"),
("saas_offered", "1"),
]
print("http://localhost:8001/oauth/mcp/authorize?" + u.urlencode(q))
PY

Open that URL as dev@localhost. If identity shows its sign-in page, finish the Mailpit link in this browser, then return to the same URL. On consent, check the services you want. Identity pre-checks identity and adds ai because the resource is the gateway. Those boxes are POST fields named services, not authorize query parameters. include_saas is a separate checkbox, shown only when saas_offered=1 is set. Its label is "Also allow SaaS tools (global Shellui account sign-in required)". Leave include_saas unchecked until Terms are accepted. Click Allow. The listener stores code.

Token​

Authorization-server metadata lists token_endpoint as POST /oauth/token. POST /oauth/mcp/token is the same handler. Send form fields, not JSON, so repeated keys survive. This block uses the saved client id, the captured code, and the PKCE verifier.

CODE=$(cat /tmp/shellui-mcp-code)
CID=$(cat /tmp/shellui-mcp-client)
V=$(cat /tmp/shellui-mcp-verifier)
curl -sS -X POST "http://localhost:8001/oauth/mcp/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "client_id=${CID}" \
--data-urlencode "code=${CODE}" \
--data-urlencode "redirect_uri=http://127.0.0.1:8765/callback" \
--data-urlencode "code_verifier=${V}" \
--data-urlencode "resource=http://localhost:8006/c/1/mcp" \
-o /tmp/shellui-mcp-token.json
python3 - <<'PY'
import json
tok = json.load(open("/tmp/shellui-mcp-token.json"))
open("/tmp/shellui-mcp-access", "w").write(tok["access_token"])
print("access_token bytes", len(tok["access_token"]))
PY

Gateway tools/list​

This call returns the discovery list in Finding tools.

TOK=$(cat /tmp/shellui-mcp-access)
curl -sS -X POST "http://localhost:8006/c/1/mcp" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${TOK}" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Names use a service prefix, for example storage_list_bucket. Object list takes path parameter bucket_id on storage/v1/object/list/<bucket_id> and a body from ObjectListRequestSerializer. The gateway name is storage_create_object_list.

Finding tools​

tools/list returns a short discovery list unless you ask for the full catalog. A direct tools/call still runs any of the 224 tools. The ai-service MCP gateway handbook is the reference for names and parameters.

The default list is:

  • ai_list_services
  • ai_search_tools
  • ai_describe_tool
  • ai_call_tool
  • identity_list_users, storage_list_bucket, hosting_list_apps, and email_list_messages when the service is connected

List services, search, describe the match, then call it. ai_call_tool uses the same approvals as a direct tools/call. Search for invite tools with ai_search_tools:

{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "ai_search_tools",
"arguments": {
"query": "invite a user",
"limit": 3
}
}
}

POST http://localhost:8006/c/1/mcp?tools=all returns the full list. tools/list with params {"tools":"all"} does the same. The default MCP_TOOLS_LIST_MODE is discovery. Set it to all when the full list should be the default.

Downstream mint​

The gateway calls POST /api/v1/mcp/internal/mcp-downstream-access-token on identity with an ai-service RS256 assertion when it calls another service /mcp. The minted token aud is that resource URL. It is short-lived and per company. It is not the global agent JWT.

Approvals​

  • List: GET /api/v1/mcp/approvals with a human company token. Pending rows include service, action, tool_name, target, is_destructive, short_action_summary, and arguments_redacted (always {} for internal creates).
  • Decide: POST /api/v1/mcp/approvals/{id}/decide with {"decision":"approve"} or "deny".
  • Session: in-chat allow_session (session_allow in chat metadata) applies to non-destructive tools. Default TTL is 60s (MCP_APPROVAL_SESSION_TTL_SECONDS, clamped 30 to 60).
  • Destructive: session_allow does not apply. mcp_access ask still asks on destructive tools when full would allow other writes. New consent cannot enable destructive access without asking. allow_destructive_without_asking can remain on old Agent rows.
  • Delegated agents (global_agent_id set) must take approvals from ai-service. Storage, hosting, and email get 409 out_of_sync if they create those approvals.

Call logs​

POST /api/v1/mcp/internal/mcp-call-logs requires outcome in allowed, failed, denied, waiting_approval, or session_used. grant_version is required (JSON integer) and must match the Agent.

Delegated agents must also send global_company_id (uuid string) and company_binding_version (JSON integer). That pair plus grant_version is the authority triple. All three must match the row. A mismatch returns 409. Personal agents omit the binding fields. Session check uses the same live triple when the agent is delegated.

method must be POST and path must be /mcp.

Identity stores the label as POST /mcp with the service id. Another method or path returns 400.

Omit arguments, arguments_redacted, operation_title, and resource_label.

Revoke with POST /api/v1/mcp/agents/{id}/revoke. Poll GET /api/v1/mcp/internal/mcp-revocations as in identity-mcp.

Global token exchange (manual)​

Finish the human account and Terms first. Complete global MCP OAuth on saas-service using the authorization and token routes in its develop handbook saas-dev. This page does not fold that consent into one command, and it does not mint the subject token from Django admin.

When you have that global agent JWT, exchange it on identity. Repeated services keys belong on this form body. They narrow the global agent. They are not authorize query parameters. The subject scope is one space-separated string and must include ai. POST /oauth/token and POST /oauth/mcp/token share the handler. Human vault federation still uses handle_token_exchange on POST /oauth/token, not this grant.

G=urn:ietf:params:oauth:grant-type:token-exchange
A=urn:ietf:params:oauth:token-type:access_token
curl -sS -X POST "http://localhost:8001/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=${G}" \
--data-urlencode "subject_token=${SUBJECT_TOKEN}" \
--data-urlencode "subject_token_type=${A}" \
--data-urlencode "requested_token_type=${A}" \
--data-urlencode "company_id=1" \
--data-urlencode "resource=http://localhost:8006/c/1/mcp" \
--data-urlencode "access_mode=read_only" \
--data-urlencode "read_level=safe" \
--data-urlencode "allow_destructive=false" \
--data-urlencode "services=identity" \
--data-urlencode "services=storage"

Set SUBJECT_TOKEN to the global agent access JWT before you run it. The response is a regional token for company 1. This repo has not run mint, this exchange, a gateway approval, and a downstream call together. pnpm run test:scripts does not perform that HTTP sequence.

Local compose sets DEV_REGION_CODE to ch. Tool names for SaaS company create and retrieve stay in the saas-service handbook.

shellui.config.json (human CLI)​

{
"backend": {
"type": "shellui",
"url": "http://localhost:8001",
"companyId": "1"
},
"saas": { "url": "http://localhost:8005" }
}

REGION_CH_IDENTITY_ORIGIN labels the dashboard region row. saas.url is the base for GET /api/v1/companies/.

Shellui CLI routes (human session)​

After shellui login (device authorization; the token is not printed):

  • shellui projects list: GET {saas.url}/api/v1/companies/
  • shellui projects get <uuid>: GET {saas.url}/api/v1/companies/{uuid}/
  • shellui projects regions: GET {saas.url}/api/v1/regions/
  • shellui projects endpoints <uuid>: GET {saas.url}/api/v1/companies/{uuid}/endpoints/
  • shellui projects use <uuid>: stores the default UUID
  • shellui projects create: not implemented (projects create)

Not a one-command flow here​

  • Inspector against shellui/dev with scripted OAuth is not in this repo. Use ai-e2e or the curl above.
  • Global OAuth consent, then exchange, then approval, then a downstream tools/call is manual. Shellui pytest does not execute it.