MyPort.al for AI Agents

One authenticated surface for tools and data: REST + MCP (Streamable HTTP). Supports OAuth 2.1 + PKCE (Claude.ai, Claude Code, any MCP client) and Bearer API keys for headless agents.

Agent start — connection info

Point your MCP client at the URL below. If the main app sets NEXT_PUBLIC_MCP_URL (e.g. your Render MCP service), the app and discovery manifest both advertise that endpoint — no manual URL hunting when the agent reads the manifest.

Base URL (app + auth):

https://myport.al

MCP endpoint (Streamable HTTP — POST JSON-RPC to this URL, session via Mcp-Session-Id header):

https://myport-al.onrender.com/mcp

Using external MCP (Render, Streamable HTTP). The in-app route /api/mcp returns 410 — clients must use the URL above.

Auth (required):

Authorization: Bearer <JWT_or_mpal_API_key>

OAuth 2.1 — MCP clients like Claude.ai handle this automatically (see below). API key — long-lived mpal_... from POST /api/auth/api-keys. JWT — short-lived token from POST /api/auth/login. Tools omit userId on HTTPS MCP — the user is resolved from the token.

Discovery manifest (OpenClaw / auto-discovery):

https://myport.al/.well-known/clawl.json

JSON includes mcp, mcpTransport ("streamable-http"), mcpConnectionGuide, mcpRequiresAuth, and mcpAuth so agents can connect with zero guesswork.

OAuth 2.1 (Claude.ai, Claude Code, etc.)

MCP clients that support OAuth 2.1 (like Claude.ai and Claude Code) can connect with zero manual key management. Just add the MCP server URL — the client handles discovery, registration, login, and token exchange automatically.

Claude.ai setup

Go to Settings → Connectors → Add custom connector
Enter the MCP server URL: https://myport-al.onrender.com/mcp
Claude.ai discovers OAuth endpoints automatically
A browser window opens — sign in to your MyPort.al account and click Authorize
Done — all MCP tools are now available in your conversations

Claude Code setup

Run /mcp and add the server URL. Claude Code opens your browser for OAuth — sign in and authorize.

How it works (for client implementers)

The MCP server advertises https://myport.al as its OAuth 2.1 authorization server via /.well-known/oauth-protected-resource (RFC 9728).

The authorization server exposes:

/.well-known/oauth-authorization-server — server metadata (RFC 8414)
/api/oauth/mcp/register — Dynamic Client Registration (RFC 7591)
/oauth/authorize — authorization endpoint (consent page)
/api/oauth/mcp/token — token endpoint (returns mpal_... API key)

PKCE with S256 is required. The access token is a long-lived mpal_... API key — no refresh token needed. Revoke it anytime from your profile settings.

MCP Apps UI (interactive in chat)

The MCP server exposes an App resource MyPort.al Module View (ui://myportal/module-view). When the host supports MCP Apps, get_module_data can render structured UI instead of raw JSON — for example shopping lists with checkboxes (toggle calls execute_module_action → mark_purchased / mark_unpurchased and syncs to your dashboard), todos, notifications, and a Media Studio gallery grid.

Shopping / Walmart: assign items to a store in the app; the MCP App shows @store labels. Filter by list in the dashboard; the agent uses moduleType: "shopping-list" with your module id.
Media Studio parity: get_module_data for image-generation or video-generation returns your generated_images gallery; actions include generate, save_to_gallery, delete_from_gallery.

Quick start

One-time setup: create account, confirm email (user clicks link once), then create API key. After that, the agent operates autonomously.

# 1. Create account
curl -X POST https://myport.al/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@example.com","password":"secure-password"}'

# 2. User confirms email (one-time: click link in signup email)

# 3. Login to get JWT
curl -X POST https://myport.al/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@example.com","password":"secure-password"}'

# 4. Create API key (long-lived, for headless/agent use)
curl -X POST https://myport.al/api/auth/api-keys \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Agent"}'

# 5. Connect MCP client to the MCP URL above with Bearer mpal_<your-key>

# 6. Use API key for all requests (REST + MCP)
curl -X GET https://myport.al/api/dashboard/layout \
  -H "Authorization: Bearer mpal_<your-key>"

Authentication

OAuth 2.1 (recommended for MCP clients): Automatic via the flow above — no manual key management needed. Claude.ai, Claude Code, and other MCP clients handle this transparently.
API Key (headless agents): Use Authorization: Bearer mpal_... — long-lived, revocable in Settings. Created at POST /api/auth/api-keys (requires JWT).
JWT (short-lived): Use Authorization: Bearer <access_token> from POST /api/auth/login. Expires after 1 hour.

MCP integration (Streamable HTTP)

Connect via Model Context Protocol for tool-based access. Use the MCP URL from this page with a Bearer token. The server resolves the current user from that token — tool calls do not need a userId parameter on HTTPS MCP (stdio/local MCP may still require userId per tool).

Endpoint: https://myport-al.onrender.com/mcp

Transport: Streamable HTTP — all communication is POST to /mcp. No SSE stream to open.

Streamable HTTP connection steps

1. POST initialize (creates session):

curl -X POST https://myport-al.onrender.com/mcp \
  -H "Authorization: Bearer mpal_<key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0.0"}}}'

Save the Mcp-Session-Id response header — include it on every subsequent request.

2. POST initialized notification:

curl -X POST https://myport-al.onrender.com/mcp \
  -H "Authorization: Bearer mpal_<key>" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

3. Call tools (same endpoint + session header):

curl -X POST https://myport-al.onrender.com/mcp \
  -H "Authorization: Bearer mpal_<key>" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_user_modules","arguments":{}}}'

All requests use JSON-RPC 2.0. Tool names are bare (e.g. execute_module_action, not prefixed).

Session shortcut (skip init)

You can skip steps 1–2 entirely. If you POST a tools/call request with Authorization: Bearer <token> but no Mcp-Session-Id, the server auto-creates a session and processes your tool call in one step. Sessions also auto-recover after server restarts — as long as your Bearer header is present, you never need to re-initialize.

Self-hosted MCP (e.g. Render): set SUPABASE_SERVICE_ROLE_KEY on the MCP service so RLS-backed tables (tasks, shopping, gallery) work without a user JWT on the Supabase client. Never expose the service role key to the browser.

Companion: Use gws (Google Workspace CLI) MCP for Gmail, Calendar, Drive, Sheets, Docs.

Available MCP tools

Call tools/list for the live set. Tools are visible when the matching module is on the user's dashboard.

Core tools (always available)

Tool	Purpose
get_available_module_types	List all module types the platform supports
get_user_modules	List modules on the user's dashboard (returns id, type, etc.)
get_module_data	Fetch structured data from a specific module
get_module_summary	Get a short text summary of a module
execute_module_action	Execute any action on any module (the primary tool)

Module-specific tools

Tool	Module	Purpose
get_user_tasks	todo	List tasks
create_task	todo	Create a task
get_user_todo_lists	todo	List named to-do lists
create_todo_list	todo	Create a named to-do list
get_user_notifications	notifications	List notifications
mark_notification_read	notifications	Mark notification read
get_user_sticky_notes	sticky-notes	List sticky notes
create_sticky_note	sticky-notes	Create a sticky note
get_user_shopping_lists	shopping-list	List shopping lists
get_user_notes	notes	List notes
create_note	notes	Create a note
pin_note / unpin_note	notes	Pin/unpin notes
tag_note	notes	Tag a note
delete_note	notes	Delete a note

Webhook tools (always available)

Tool	Purpose
register_webhook	Subscribe to push events
unregister_webhook	Remove a webhook
list_webhooks	List registered webhooks
test_webhook	Send a test ping
update_webhook	Update webhook config

Tool visibility is dynamic. A tool appears when its module is admin-enabled and on the user's dashboard. Core tools (mapped to no specific module) are always visible when a valid profile exists. After adding/removing modules, call tools/list again to refresh.

API reference & ideas

OpenAPI 3.1 Spec
llms-full.txt — Detailed capability reference
clawl.json — Discovery manifest (MCP URL, transport, auth, connection guide)
Agent Guide: MCP Tools & Skip-Bo — Full walkthrough: discovery, session setup, tool listing, and playing Skip-Bo via MCP (raw markdown — agent-readable)

Module ideas for agents: use Notes and Journal for durable memory; Sticky Notes for scratch context; Goals / Todo for plans; Notifications to surface reminders; Recap-it / Daily AI Summary for digest workflows. A dedicated "agent memory" module could wrap notes with tags — today, notes + execute_module_action is the closest built-in.