Skip to main content
The MSPortal MCP server lets a compatible AI client use portal tools under your account’s access. It is separate from the built-in Home assistant: you configure and authenticate your external client before it can request MSPortal data or actions.

​
Before you start

You need an MSPortal account, access to Settings > MCP Server, and MCP Server write permission to connect or revoke clients. Read-only settings access lets you inspect the page but does not authorize a connection. Your MSP administers Company-user permissions. Choose a client that supports remote Streamable HTTP MCP and browser OAuth authentication. A generic MCP setting or local-server support alone is not enough. Your client subscription and organization policies can also affect availability. The connection uses browser sign-in and OAuth consent rather than a portal API key. Data returned by tools goes to the external AI client you connect, under that service’s handling and your organization’s policies. Connect only the areas you intend to use.

​
Connect your client

1

Copy the correct server URL

Open Settings > MCP Server and copy Server URL. Use the URL shown by your own regional portal. Each person authenticates with their own account; copying the URL does not copy another person’s access.
2

Choose the client setup card

Under Connect your client, choose the matching client. The dialog provides a command, configuration or install link where supported. Opening the dialog or copying a snippet does not connect the client.
3

Add the remote server in the client

Follow the matching instructions. A one-click install link opens a client application; the client may still ask you to trust or start the server. For Copilot, use the dedicated guide.
4

Authenticate and review consent

Complete the browser sign-in and normal account verification. Review the requested read/write areas before approving. If the client or requested access is unexpected, cancel. Role permissions and company scope still limit approved OAuth access.
5

Verify a real connection

Check the client’s server status and available tools. Ask it to use get_current_user to verify the connected identity and company context. A prose answer listing possible tools without a tool call is not connection verification.
Codex MCP setup dialog with command, configuration and browser sign-in instructions.

MSP setup dialog; no client authorization submitted.

​
Codex CLI

Replace the quoted placeholder with the Server URL copied from MSPortal:
Complete browser authorization when prompted. The equivalent server entry belongs under [mcp_servers.msportal] in Codex configuration, with url set to the copied URL. See official OpenAI MCP instructions for client configuration and tool controls.

​
Other clients

Use the matching in-app card for Claude Code, Claude Desktop/Web, Cursor, GitHub Copilot in VS Code, Gemini CLI, Windsurf or other compatible clients. Configuration formats differ: do not paste another client’s JSON or CLI syntax unchanged. Client releases can change menus; use that client’s current documentation when its interface differs from the card.

​
What an assistant can do

Tools cover tickets, devices, reporting, Planner, goals, budgets, meetings, compliance, projects, financial data, cloud services, security, backup, surveys, training, onboarding and other supported areas. Read the MCP Tools Reference for exact capabilities and action behavior. The available set depends on deployed tools, consent scopes, your role, company access, provider availability and client-side selection. A Company identity does not inherit MSP-only tools by granting broader scopes. List results can be paginated or truncated; a small response is not proof of a complete portfolio search.

​
A smaller tool catalog

The consolidated catalog groups related operations into 93 public tools, covering the same 260 existing operations. Read tools use names such as query_planner; changes use names such as manage_planner, with a separate action for creating, editing or archiving an item. The assistant uses the input schema to choose the action and its arguments. The full catalog fits below a 128-tool client budget without deselecting feature areas. Your consent screen counts the grouped tools available to your account. Scopes, role permissions and company access still apply to each action, and other connected servers may contribute additional tools to your client’s total. The exact catalog depends on the deployed server version.

​
Existing connections

Existing tool names remain callable with their original arguments and response shapes, including the two compatibility aliases. Pending confirmations retain their original operation identity and expiry. You do not need to change the server URL or grant broader access just because the catalog is consolidated. When your client refreshes its tool list, it sees the grouped names. Update any tool-name allowlist when adopting those names. Custom clients that require old names to appear in tools/list must update their discovery logic; preserving old calls does not preserve the old discovery response. See grouped calls and legacy compatibility. A useful first request is: “Use read tools to identify the company I name and summarize the available evidence. Do not change records or send messages.” Check cited records, dates and gaps before requesting follow-up work.

​
Confirmation before changes

Most portal mutations use a proposal/confirmation flow:
  1. Request the proposed change and inspect the returned preview, company, records and effects.
  2. Approve that proposal only when it matches your intent.
  3. The client confirms the staged proposal before it expires, normally within ten minutes.
  4. Verify the resulting record or background operation. An accepted job request is not proof of completed provider delivery.
The confirmation applies the stored proposal. To change its target or values, request a new proposal and review it again. An expired or already-used confirmation cannot be reused. A staging response is not evidence that a business record was created.
Not every tool has a server confirmation round trip. mark_notification_read changes your notification state immediately. draft_compliance_notes generates drafts without saving them. submit_feedback sends a message to MSPortal immediately and must only be used when you explicitly ask to send feedback; finding a missing capability does not authorize a message. Inspect each tool’s behavior rather than relying on a blanket read/write label.
If a write times out or returns an uncertain result, inspect the target record before asking the assistant to repeat it. Multi-step workflows and external side effects should not be assumed to roll back together.

​
Ron: the AI vCIO skill

The optional Ron skill provides instructions for client briefings, risk reviews, QBR preparation and planning. It does not establish an MCP connection or grant permissions, and cannot guarantee that every client follows its instructions. The published package has a SKILL.md, references/playbooks.md and references/tool-map.md. Review and install the files together using your client’s supported skill or instruction mechanism. Preserve their relative paths. Do not blindly append downloaded content to an existing project instruction file. Use the published Ron skill, playbooks and tool map, or the matching paths on your regional portal. Keep your chosen instructions consistent with the actual tool confirmation and immediate-action behavior above. An assistant answering without tool calls does not prove the skill failed to load. Check server connectivity, enabled tools and the actual calls made; ask for an evidence-backed answer.

​
Connected clients and revocation

Connected clients lists the applications authorized by your current user, with their names, first-party/external labels, last-authorized time, session count and scopes. It is not a tenant-wide inventory of every employee’s clients. Session counts describe active refresh-token sessions, not a live count of open browser tabs. Select Revoke for the intended client and confirm to revoke your grant and refresh sessions. There is no separate page Save. Already-issued access tokens can remain valid until expiry, up to about 15 minutes. Removing the user’s MCP Server write permission blocks subsequent MCP requests through the permission check. Ask the MSP administrator to make role changes when required. Revocation does not erase data already returned to the external client, undo completed actions or remove the local server configuration. Reconnection requires authentication and consent again.

​
Troubleshooting

​
Frequently asked questions

No. Add the URL in a compatible client, authenticate and approve the requested access. Copying a snippet or opening a setup dialog does not connect anything.
No. Connecting requires MCP Server write permission. Ask your MSP administrator to review your role.
No. Scopes, role permissions, company scope and tool-specific restrictions all apply. Company identities remain subject to MSP-only restrictions.
The 260 legacy names remain callable with their original arguments and result shapes, and pending confirmations retain their operation identity. Discovery now returns grouped names, so client allowlists and custom discovery checks may need updating. Existing grants do not expand automatically.
No. A proposal awaits confirmation. Inspect the final result and target record after confirming.
Request a new proposal instead. The confirmation commits the stored proposal, not a newly described change.
No. Some actions run immediately, including marking notifications and sending explicitly requested feedback. Read the tool reference before authorizing them.
It should not. submit_feedback is MSP-only and requires your explicit request to send feedback; discovering a limitation is insufficient.
It revokes the grant and refresh sessions, but an issued access token can remain valid until expiry, up to about 15 minutes. MCP permission removal is checked on subsequent requests.
No. It does not recall returned data, undo completed work or delete the client’s local configuration.
No. It is optional client guidance. The MCP connection, consent and server access checks remain separate.