> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aioncx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol

> Connect agents to Mach-1 processing or native Atlas workforce tools.

## Mach-1 MCP: conversation processing and results

Use the deployed `https://build.aioncx.com/api/mcp` endpoint with a personal `atlas_ingest_` scoped key from [Build Developers](https://build.aioncx.com/build/developers). A submit-and-read key can send an audio URL or transcript and read results. A read-only key can inspect authorized data. Organization ingest keys with more than one workspace grant must select a workspace. Native Zoom reads also require the issuing person's current recording authority. The key is checked against current grants on each call.

The conversation tools include `mach1_get_transport`, `mach1_list_analysis_definitions`, `mach1_list_interactions`, `mach1_submit_audio_url`, `mach1_submit_transcript`, `mach1_get_status`, `mach1_get_transcript`, `mach1_get_results`, and `mach1_get_recording`. Discover the actual visible inventory with `tools/list`. Use `mach1_get_transport` to discover the direct receiver for audio bytes and large transcripts. MCP JSON requests have a 64 KiB limit. Submission is asynchronous and analysis is charged per configured transcript minute for each selected Definition; omitted Definition IDs request no analysis. Use stable idempotency keys for uncertain retries and follow `next_actions` for polling or pages.

The runnable Mastra example and evaluation commands are in [`examples/mach1-mastra`](https://github.com/Xaqt/atlas/tree/main/examples/mach1-mastra). It calls these same tools with schema validation. An agent must receive real text/turns or an admitted interaction ID; a local filename alone gives it no file access.

## Mach-1 MCP: forecasting

Forecasting uses the same application endpoint with explicitly granted `forecast:read` and `forecast:submit`. The tools are `mach1_list_forecast_sources`, `mach1_submit_forecast`, and `mach1_get_forecast`.

Use the [forecasting request schema](https://docs.aioncx.com/api-reference/forecasting/overview.md) for numerical history or a discovered metric. Submission takes `request` and a stable `idempotency_key`; reads take `run_id`, optional pagination, and the retained quantile selection. A native Atlas connection uses separately granted `atlas_list_forecast_sources`, `atlas_submit_forecast`, and `atlas_get_forecast` tools.

See the [agent quickstart](https://docs.aioncx.com/agents/quickstart.md) and [forecasting pricing](https://docs.aioncx.com/mach1/forecasting-pricing.md).

## Documentation MCP: public search

The public [Build on AionCX documentation](https://ventures-cx.mintlify.app) exposes a separate [Documentation MCP endpoint](https://ventures-cx.mintlify.app/mcp). It searches published Markdown content and does not submit or bill processing. Mintlify also generates [`llms.txt`](https://ventures-cx.mintlify.app/llms.txt) and [`llms-full.txt`](https://ventures-cx.mintlify.app/llms-full.txt). Keep the documentation-search endpoint and the Mach-1 processing endpoint distinct in agent configuration.

## Native Atlas MCP: workforce and scheduling

After this release is deployed, open **Settings → External agents → Manage MCP
connections** (`/atlas/settings/mcp`). You must have `manage_schedules` authority. Each tool also checks the same capability as its Atlas screen: directory/email discovery requires `manage_authorization`, employment and group-member reads require `view_workforce_context`, and group membership changes require `manage_workforce_roster`. A token never grants these capabilities by itself.
Select the workspaces and whether to allow draft writes. Create a connection,
then copy its token directly into your client's secret configuration. Never paste
it into a conversation, source file, or a URL.

The endpoint is `https://atlas.endeavorcx.com/api/mcp`. It uses stateless Streamable
HTTP with JSON responses and protocol version `2025-06-18`. Authenticate with
`Authorization: Bearer <connection-token>`. OAuth login is not offered by this
release; use the explicit bearer-token connection.

For Codex, make the token available to the client process as `ATLAS_MCP_TOKEN`,
and configure:

```toml theme={"system"}
[mcp_servers.atlas]
url = "https://atlas.endeavorcx.com/api/mcp"
bearer_token_env_var = "ATLAS_MCP_TOKEN"
```

Restart the MCP connection and verify `atlas_list_workspaces`. For this native-tool
branch, do not use browser cookies, service-role keys, direct database connections,
or Mach-1 ingest credentials.

Custom connections expire in seven days; the explicit Superadmin profile stays
valid until revoked while its issuer remains an active superadmin. Only a hash
is stored. Revoke a connection from the same Settings page. Each domain intersects
its workspace grants with the issuing person's current business authority.
Removing that authority, disabling the person, revoking the token or expiry
removes access. Custom connections keep fixed workspace selections. The explicit
Superadmin profile follows active, organization-bound workspaces, including new
ones, while retaining its separately selected action permissions.

## Roster and schedule workflow

1. `atlas_list_workspaces` discovers the authorized workspaces and durable IDs.

2. `atlas_list_people` pages through each workspace's directory. For an
   existing account absent from every workspace roster, an organization
   administrator can use `atlas_find_organization_person` with an exact email
   and one granted workspace. It can find org-only people, returns Atlas
   `person_id`, Auth-link status and association evidence, and marks the
   connection owner separately. A global person with no association to that
   organization is not exposed. Multiple matches remain ambiguous. Read
   `association_sources`, `status`, and `workspace_access`: agent assignment
   and employment do not themselves confer login access. Never guess or
   silently create duplicate people.

3. `atlas_get_scheduling_context` supplies scoped employment assignments. Respect
   effective dates and employment status. In enforcement mode, missing assignment
   context is a constraint, not permission to fall back to a person-only roster.

4. `atlas_list_schedule_groups` and `atlas_get_schedule_group` show existing
   groups, membership, operating hours and timezones. With write scope, use
   `atlas_create_schedule_group` and `atlas_add_schedule_group_member` as needed.

5. `atlas_list_schedules` checks existing periods and display names before
   `atlas_create_schedule` creates a **draft**. Supply an optional, clear
   `name` (for example, "Support team schedule — 2026-09-28"),
   local calendar dates for the period, and explicit UTC/offset timestamps
   for `atlas_add_schedule_shift`. `atlas_get_schedule` reads the saved
   display name back. Interpret the roster in its confirmed timezone and
   account for daylight-saving transitions. Existing schedules cannot
   overlap for the same group, even when named differently.

6. `atlas_list_activity_types` discovers break/meal activity slugs.
   `atlas_add_schedule_activity` places explicitly timed activities. A meal
   duration without a placement does not authorize inventing a break time.

7. `atlas_get_schedule` reads back the result and `atlas_validate_schedule` runs
   the existing work-rule validator.

8. With the separate **Schedule publication** permission, use
   `atlas_publish_schedule` after reviewing the draft and validation results.
   Pass the exact `updatedAt` returned by `atlas_get_schedule` as
   `base_updated_at`, a stable UUID `request_id`, and only acknowledge warnings
   that were reviewed. The existing Action command applies current authorization,
   work rules and approval policies. A `pending_approval` result is not published:
   retain the request and resume with the same arguments after human approval.
   Retry uncertain outcomes with the same request ID and viewed revision.

Existing draft-write connections do not receive publication permission. Enable it
explicitly in **Your connections**; a scheduling-write grant is also required.
The database verifies the active token, owner, workspace and publication scope
again at request and commit. Audit evidence records the real API-token actor and
issuing person. Published schedules cannot be edited through this MCP surface.

## Workspace access roles

Use `atlas_get_workspace_access` to read the existing person's role, status and
`authorization_revision` in each granted workspace. With the separate
**Workspace access roles** permission, call `atlas_set_workspace_access_role`
with the observed revision, desired role and a stable UUID `operation_key`.
Only use a null expected revision when the membership is absent. Confirm the
person's identity before writing; these tools do not create users or invitations.

Roles use the existing Atlas definitions: `member` grants full product access;
`skyway_agent` and `desktop_agent` are restricted agent access. The connection
owner must currently be an organization administrator for the workspace (or a
root administrator). Self changes, restricting root users, stale revisions and
foreign-organization targets are refused by the existing atomic access command.
Pending invitations stay pending. The audit event records the owner and token.
Read back each workspace after a change; retry lost responses with exactly the
same operation key and arguments. Never assume granted workspaces are every
workspace in the organization.

Both new permissions can be enabled or revoked on an existing connection without
rotating its token or changing its expiry or workspace grants. Scheduling and
routing permissions remain separate.

Writes use the existing scheduling services and their workspace, assignment,
period, state, and work-rule checks. They are not automatically retried: after a
lost response, read the target group or schedule to determine whether the write
committed before submitting again. Group and schedule lists use existing service
limits; a large roster that cannot be read completely must be reported as a
constraint rather than treated as a complete employee inventory.

The older semantic, inbox and mail MCP-shaped routes remain separate authenticated
application surfaces. They are not included in these workforce connection grants.

## Onboard new Skyway people

After the onboarding migration and application are deployed, enable **Create
people with workspace access**, **Send login invitations**, and **Provision
Skyway voice for people** under the existing connection's permissions. These
are independent opt-ins: existing connections, including Superadmin profiles,
retain their current grants. Updating them does not rotate the bearer token.
Refresh the client's tool inventory afterward.

Person creation needs `mcp:people:create` plus `mcp:access:write` in a granted
workforce workspace. Invitations need `mcp:people:invite`. Both require current
organization People & Access administration (or Organization Administrator /
active superadmin). Voice provisioning needs `mcp:routing:voice:write` plus
routing-read/write in a granted routing workspace and current
`manage_ccaas_configuration`. Scheduling and AI-agent grants alone do not
enable voice provisioning.

1. Find the authorized workspace and check `atlas_find_organization_person`
   using each confirmed human's exact email. For an existing person, use their
   confirmed `person_id` and the workspace-access tools. An ambiguous match
   needs an explicit identity choice. For a confirmed new human, call
   `atlas_create_person` with `workspace_id`, a stable UUID `operation_key`,
   `name`, `email`, and the explicit `access_role` (normally `skyway_agent`).
   Creation and restricted access commit together. The response includes the
   durable `person_id` and current access; it does not send email.
2. Read `skyway_get_person_voice_access`, then use
   `skyway_enable_person_voice` with the workspace and person IDs. Atlas uses
   the same person-first provisioning service as Voice Access. If multiple
   operational identities exist, the error returns candidates; supply only
   the confirmed `agent_object_record_id` as the recovery choice. The response
   includes `agent_object_record_id` for queue assignment and binding status.
   Credentials, passwords and provider secrets are never returned.
3. Inspect existing queues through `skyway_get_queue` and add the returned
   agent ID with `skyway_set_queue_agent`. Outbound-only people belong to their
   outbound queue; blended people also join the inbound service queue. Read
   each queue back. Membership affects future work immediately and does not
   make a phone registered or an agent ready.
4. Once the access role is final, explicitly call `atlas_invite_person` with
   a separate stable UUID `operation_key`, `person_id`, and `workspace_id`.
   The database reads and validates the selected person's saved email; the tool
   has no recipient override. Correct an incorrect email in the person record
   first. This sends email and grants no additional access. Inspect
   `atlas_list_person_invitations` for delivery, expiration,
   revocation and acceptance. A delivered invitation can still be pending;
   it is not proof of active login access.

For several people, repeat this workflow with distinct creation and invitation
keys per human. Reuse the exact key and arguments after an uncertain response.
Person creation never merges identities by name/email. Voice retries recover
the existing dedicated login; read status before retrying. A recorded successful
invitation delivery is not resent. Failed or unrecorded deliveries can be retried
and may send another email; delivery is not exactly once. Changing access after
invitation preparation invalidates its revision, so use a fresh invitation key
after reviewing the new access. A saved email change also rejects an old
invitation key; use a fresh key after correcting the person record. Employment
and scheduling remain separate.

## Connected agents missing from People

Provider agent records are operational slots, not automatically scheduling people.
An organization administrator can use `atlas_list_provider_agents` in a granted
workspace to discover their source email, existing person link, state and
`enrollment_key`. Discovery returns only the requested workspace's assignments.
It fails explicitly if an underlying inventory may be truncated.

To enroll a confirmed human, enable **Agent enrollment** on an existing connection
under **Your connections**, or create a connection with **Allow enrolling connected
agents as people for scheduling** enabled. Updating a connection preserves its
token, expiry, workspace grants and scheduling permission. This adds the separate
`mcp:people:enroll` scope; existing scheduling-write tokens do not gain it.
Enrollment rechecks the owner's active organization-admin (or superadmin)
authority on every call, as does discovery. Schedule-writing permission remains
independent. Refresh client tool discovery after enabling enrollment. The existing bearer token
continues to work; it does not need to be copied or replaced.

Pass the source `provider_resource_id`, the unchanged `enrollment_key`, and either
a confirmed new person's `name` or an existing, active workspace `person_id`.
Do not infer that two people are the same from email or name alone. When multiple
provider resources represent the same confirmed person, enroll the first, read
back the person through `atlas_list_people`, and explicitly use that person ID
for the other resource. Never create a new person for every matching source row.

The existing atomic `atlas_enroll_provider_person` authority checks source
assignment, conflicts and lifecycle generation and records an enrollment receipt
with the human issuer. Retry a lost response with exactly the same arguments and
key; do not replace the key on retry. Enrollment creates/links the scheduling
identity only: no login membership, invitation, employment or schedule publication.
Read `atlas_list_people` afterward before continuing with schedule groups.

## Verify time-off approval routing

`atlas_get_timeoff_approval_setup` reads the published time-off practice,
WFM Manager routing policy, and currently effective WFM Manager role holders
in a granted workspace. It requires the issuing person's current
`manage_time_off_context` capability. Use it to verify the existing routing
before asking an agent to submit a request; it never installs a practice,
adds a reviewer, or approves a request. A published schedule and time-off
approval routing are separate setup checks.

## Grant boundaries

### QA Forms and LOB Lists

After the Quality MCP application and command migration are deployed, enable
**Quality access** on the existing connection in Settings → MCP Connections.
Select the workspaces and grant reading, draft editing and release publication
separately. Existing tokens retain their other access and do not gain Quality
permissions automatically. Each call checks current evaluation-program authority;
AI evaluator generation and release also require AI configuration authority.

Use `atlas_list_quality_forms` and `atlas_get_quality_form` to read the existing
Form, then `atlas_list_quality_scope_lists` and `atlas_get_quality_scope_list` to
discover the existing shared LOB Lists of queues. Question scope uses a List ID;
voice is the supported first release and has no channel selector. Outside the
selected List, a question becomes N/A without changing the agent's score.

`atlas_save_quality_form_draft` creates or edits a successor on the same Form.
Preview supplied answers on canonical calls with `atlas_preview_quality_evaluation`,
then inspect and generate the native evaluator with
`atlas_preview_quality_prompt` and `atlas_create_quality_prompt_draft`. Review
`atlas_preview_quality_release` before using `atlas_publish_quality_release`.
The release commits the Form, evaluator and replacement steps in existing
pipelines together, preserving target assignments and other steps. Stale plans
are refused; use the same request UUID and exact input to recover a lost response.

See the [Quality MCP workflow](https://github.com/Xaqt/atlas/blob/main/docs/atlas/mcp-quality.md)
for the Nevada critical-failure and outside-LOB N/A setup. QA checks do not send
surveys or implement a survey activation gate.

### Bind an inbound phone number

Routing publication does not grant phone-number activation. Enable **Bind inbound
numbers** under an existing connection's access settings, or explicitly select it
when creating a custom connection. This adds `mcp:routing:numbers:write`, requires
routing-write access and current call-configuration authority in every granted
routing workspace, and preserves the token and its unrelated permissions.
Existing connections and the superadmin creation preset do not gain it implicitly.

Discover the number ID with `skyway_queue_options` or `skyway_get_queue`, then
use `skyway_get_number_binding` to read its E.164, status, current route and
`inbound_config_revision`, plus the last binding's reviewed version, actor and
timestamp. Read and review the exact current published version through
`skyway_get_route`. After the operator approves that cutover, call
`skyway_bind_number` with `workspace_id`, `phoneNumberId`, `expectedRevision`,
`flowId`, `expectedPublishedVersionId` and `approveRoutingChange: true`.

Binding uses the existing activation service and atomic number/publication
revision checks. It preserves outbound caller ID, recording override and number
status. New inbound calls on an active number use the route immediately; existing
calls keep their pinned version. An inactive number remains inactive. This does
not publish a route, place a test call, grant audio-deletion authority or bypass
recording/provider readiness checks.

Read the binding back after success or a lost response. If the number revision or
published route changed, inspect and review the new state rather than automatically
retrying with a new revision. Live caller and agent testing is still required.

### Workspace access

`atlas_list_workspaces` is the connection's scheduling-workspace grant list,
intersected with its owner's current authority. It is not the list of every
workspace in Atlas or even every workspace in the organization. Workspace role
changes require explicit grants for each target workspace. An org admin can
look up an org-only person from any granted workspace, but that lookup does not
expand the connection's workspace grants or grant the person login access.
If the desired workspace is absent, create a new connection selecting that
workspace; existing connection workspace grants cannot be widened in place.
Do this before attempting the write;
never substitute a service-role query or browser action.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.