How the MCP Works

This page covers what happens under the hood when an AI assistant is connected to ScopeStack: how it authenticates, what it’s allowed to do, and the conventions that shape its responses. You don’t need any of this to use the MCP, but it helps when you’re troubleshooting or building a more involved workflow.

Authentication & Account Scoping

The MCP server lives at a single endpoint, https://api.scopestack.io/mcp, and speaks the standard MCP protocol over HTTP. Every request carries an OAuth bearer token — the same kind of token the ScopeStack REST API uses. Your AI client obtains that token through the browser login the first time it connects (see Connecting Your AI Assistant).

The token is tied to your user, and your user belongs to one account. The server resolves the account from your login on every request, so an assistant always works inside your account and can’t reach another. Tokens carry read and write scope.

Permissions

MCP tools enforce the same role permissions as the rest of ScopeStack. Before a tool runs, the server checks that your role allows that action — the identical check the web app makes. If your role can’t do something in the UI, the assistant can’t do it through the MCP either, and the tool returns a “your role does not have permission” message.

A few examples of the permission each action needs:

If an assistant reports it can’t do something, this is usually why — ask your account admin to adjust your role.

Conventions

Pagination. Search and list tools that can return many rows accept limit (default 25, max 100) and offset. They return a count alongside the page of results, so an assistant can page through large catalogs.

Errors. When something can’t be done, a tool returns a clear message — for example, a validation error from ScopeStack, or a permission error. Unexpected internal errors return a generic “please try again or contact support” message rather than technical detail.

Rate limit. Each login can make up to 200 requests per minute. Past that, requests are paused with a message telling the assistant how many seconds to wait. Normal scoping sessions stay well under this.

Recommended workflow. The tool_guidance tool returns ScopeStack’s recommended order of operations and common flows. Assistants are prompted to consult it, and to check your existing blueprints and catalog before generating new content, so results match your standards.

How a Project Gets Built

Most tools hand an ID to the next one. A typical “build a project from scratch” sequence looks like this:

1. list_rate_tables finds the rate table to price against.
2. list_resource_rates (using that rate table) finds the billable roles.
3. search_clients finds the client (or create_project creates one from a name).
4. create_project returns a new project_id used by everything that follows.
5. add_resource_rate_to_project puts a role on the project and returns a project_resource_id.
6. search_services finds catalog services to add.
7. add_service_to_project adds a service (using the project, resource, and category) and returns a project_service_id.
8. update_service_language writes deliverables and assumptions for that service.
9. review_project_scope scores the result so you can fix gaps before generating the SOW.

You’d never type this out — you’d ask, “Build an Office 365 migration project for Acme with planning, migration, and training services,” and the assistant walks the sequence for you. Naming the client, services, and phases you have in mind makes its choices more accurate.

For the full list of tools and their inputs, see the MCP Tool Reference.