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 identifies your user and carries read and write scope. ScopeStack looks up your active account on every MCP request. If you switch accounts in ScopeStack, subsequent calls under the same login use the newly active account. Before asking the assistant to write anything after a switch, run scopestack_whoami to confirm the account.
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:
| Action | Permission it checks |
|---|---|
| Create or update a project, including changing its rate table | Projects · Project Overview |
| Add a phase to a project | Projects · Project Phases |
| Add or change services | Projects · Services |
| Write Service Descriptions | Projects · SOW Language |
| Add resources or pricing adjustments | Projects · Resource Rates |
| Add products | Projects · Materials |
| Apply or answer questionnaires | Projects · Surveys |
| Create or edit catalog services, including their AI instructions | Settings · Professional Services |
| Create questionnaires | Settings · Questionnaires |
| View blueprints | Settings · Blueprints |
If an assistant reports it can’t do something, this is usually why — ask your account admin to adjust your role.
Editing project details, scope, or service language also requires the project to be in Building. Re-scoping an approved project withdraws its approval. Confirm with the project owner before re-scoping it.
Projects · Project Phases has only two levels, None and Manage, and ScopeStack’s default Admin, User and Sales roles set it to None. Adding a phase through the MCP usually means your admin has to grant Manage first.
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. The default is 200 requests per 60 seconds per access token. On HTTP 429, wait the number of seconds in Retry-After before retrying.
Recommended workflow. The scopestack_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:
scopestack_list_settingswithmodel: "rate-tables"finds the rate table to price against.scopestack_list_settingswithmodel: "resource-rates", filtered to that rate table’srate_table_id, finds the billable roles.scopestack_list_settingswithmodel: "clients"finds the client (or the next step creates one from a name).scopestack_project_item_writewithtype: "project",action: "upsert"and noproject_idcreates the project and returns a newproject_idused by everything that follows.scopestack_project_item_writewithtype: "resource_rate"puts a role on the project and returns aproject_resource_id.scopestack_list_settingswithmodel: "services"finds catalog services to add. Withresponse_format: "full", each service and subservice also carries anyai_instructionsyour account wrote for it.- If the project needs a phase it doesn’t have,
scopestack_project_item_writewithtype: "phase"adds one: one of the account’s standard phases byphase_id, or a custom phase for this project only byname. scopestack_project_item_writewithtype: "service"adds a service (using the project, resource, and category, plus an optionalphase_nameto place it in a phase) and returns aproject_service_id. The response includes the service’sai_instructions, whichscopestack_tool_guidancetells the assistant to follow while scoping that service.- Call
scopestack_tool_guidanceforpermitted_language_fields, then usescopestack_update_service_languageto write fields that are active on the account, such as deliverables or assumptions. Use the separateservice_descriptioninput for the description itself. scopestack_list_project_itemswithtype: "scope_review"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.
AI Instructions on Services
Your account can attach AI instructions to a catalog service or subservice. These are notes written for AI assistants about how to scope that service, such as questions to ask, companion services to consider, or constraints to respect. Someone whose role can edit catalog services writes them through the API, or through the assistant with scopestack_settings_write and the ai_instructions field, up to 4,000 characters.
The assistant sees them in catalog service details, in the response when it adds a service to a project, and on every service and subservice in the project overview. scopestack_tool_guidance tells it to follow them while scoping and never to copy them into service descriptions, SOW language, or any other text your client reads. They guide the assistant only. They don’t change what your role allows it to do.
When an edit made through the MCP or the API changes only the AI instructions of an existing service or subservice, or a service’s Guidance Language, it usually doesn’t send the service to Pending for approval. Any other change follows the usual approval rules.
Changing a Project’s Rate Table
To move an existing project to a different rate table, the project must be in Building and your role needs Manage on Project Overview. The assistant calls scopestack_project_item_write with type: "project", action: "upsert", the project_id and the new rate_table_id. The rate table must be an active one on your account. Any other ID is rejected and the project is left unchanged.
Changing the rate table re-prices the project’s standard resources and the services that use them. Every standard resource takes the new table’s rates, which replaces any rate, external name or description that was changed on the project itself. Vendor resources and products keep their current prices. If the new table uses a different currency, the project switches to that currency. A standard resource is removed from the project when the new table has no matching rate for it. A rate matches only when it is for the same resource and the same line of business or service category, so a resource priced for one line of business is removed if the new table has only an All Lines of Business rate for it, and the reverse. Review the project’s resources and pricing after the change.
For the full list of tools and their inputs, see the MCP Tool Reference.
New to ScopeStack?
ScopeStack automates scoping, pricing, and SOW generation for IT services teams. See how it fits your process.