Connect an AI client (MCP)

MCP creation of applications and capabilities has no Atlas plan-based count cap during Early Access. The connected identity's workspace permissions and write policy still determine whether a change is created directly or submitted for review.

Model Context Protocol (MCP) gives an AI client a structured way to call tools provided by Atlas. The aim is to let you work with your architecture from a supported AI client while Atlas manages the underlying records and access.

Check availability first

Atlas has an MCP endpoint at https://atlas.spekir.com/mcp. Access depends on the authentication setup, the tools enabled for your workspace and your role. The presence of this endpoint does not mean that every AI client can already complete sign-in or use every Atlas feature.

Ask your Atlas administrator which connection method is enabled. A legacy API-token connection and the newer OAuth connection have different setup steps; do not substitute one for the other.

Start with a read

To inspect the model before reading records, ask for get_metamodel with scope: "reference". It returns the same fact sheet type catalogue as Settings, including reference defaults and current Atlas availability. The default all response and atlas://metamodel include this as reference_profile; planned reference types remain separate from the existing entity_types and cannot be used as entity write types.

Once your administrator has confirmed a working connection:

1. Confirm the workspace the client is using.
2. Ask it to list the applications it can access.
3. Ask a bounded question, such as “Which recorded dependencies involve our CRM?”
4. Compare the answer with the records in Atlas and check the sources.

An answer covers the records and tools the client can access, not necessarily the full landscape.

A deleted application is archived, not removed. MCP reads such as list_applications, get_application, get_app_context and get_application_dependencies no longer return it, and a new application may reuse its name. It can be restored for 90 days, after which it is deleted permanently. See Applications.

Asked about business capabilities, the client can use list_capabilities. Each capability comes with its tier, its external id and its APQC references: the primary reference first, then up to three secondary, each with a strength (strong, partial or thin), a reason and whether it still needs review. A reference marked as needing review was proposed by AI and has not been checked by a person.

Ask your client to call show_cio_brief to open the CIO brief. A client that supports MCP Apps shows it as a view; any other client receives the same brief as text. It is a read: it takes no parameters, uses the workspace and access of your connection, and applies the same masking and limits as get_dataset. The view does not call other tools or change anything in Atlas.

A question such as “Which integrations and interfaces does our webshop have?” uses get_application_dependencies. Besides the recorded dependencies, it returns the application's integrations, each with the interface it leaves from or arrives at and its authentication, frequency, delivery pattern and initiator, and the application's input and output interfaces with the integrations and data objects that use them.

Draw a landscape

A question such as “Show our ERP landscape and its integration points” can be answered with the export_archimate tool. The client names the application to centre on, and Atlas returns the applications it integrates with, their interfaces, capabilities, processes, organizations and technology as an ArchiMate Model Exchange File with two laid-out views, Integrations and Layered landscape. On request it also returns a drawing of each view, which the client can show, and the file, which Archi and other ArchiMate tools import.

Atlas runs no AI for this answer. The client picks the scope from your words; every element in the drawing and the file is a record in Atlas with its Atlas ID. The answer also says what it does not contain, for example decisions and initiatives, so a missing element is not read as a missing record.

Be explicit about writes

Before asking a client to change records, ask for the proposed changes, the source for each material statement and the affected applications or relationships. Confirm the intended workspace and scope.

What a client may write depends on your workspace's change management mode and your role. Ask the client to call get_identity first: it returns the mode and, under change_governance, how your writes land. In Simple mode a person with a write role can edit directly. In Review mode only the owner of an element or an admin writes directly; other changes become proposals or change requests that someone else approves. Agents always propose, and you cannot approve from a client a proposal you created from that client. The same rule holds for every kind of item, including data object links (data_object link and unlink items, which say what an application creates, reads, updates or deletes): in Review mode such a link counts as yours when you own the application. An integration's data objects and middleware are written the same way: a data_object item with interface_id instead of application_id, and a technology link item whose target is the IT component and whose payload names interface_id; such a link counts as yours when you own the integration. A data_object link can instead carry capability_id to record which business capability uses the data object; it then counts as yours when you own the capability. See Change requests and review. Use a read-only connection where that is the required boundary.

Check a draft before submitting it

Ask your client to call validate_changes with the same changes it would send to propose_changes. Atlas checks the draft and returns whether it is valid, the affected field and reason for each error, any warnings and the number of changes. It creates no proposal and changes no records. If Atlas matched an update or deletion by name, the warning includes the matched record's ID so you can check it.

Fix the errors and review the warnings before submitting the changes. Validation follows the current proposal checks; some checks still happen when a reviewer accepts a proposal. A valid result does not reserve a name, guarantee approval or give you permission to write. Your workspace, role and change management mode still determine what happens when you submit.

Work with change requests from your client

A connector or import proposal in an open change request is decided through that change request: review_populate_proposal refuses it and names the change request.

A client can frame and move change requests the same way as Governance › Change requests. Ask it to create a change request with a title that names the intent and items that change an application's name, description, vendor or lifecycle stage; nothing changes until the change request is applied or approved. Ask it to read a change request first: the answer lists the actions you may take, such as submit, approve, reject with a note or request revision with a note. Approval writes a decision record. A change request you created from a client cannot be approved or applied by you from a client; approve it in Atlas or ask a reviewer.

Active requests in Atlas and MCP

The Active change request selector in the Atlas header applies to editing on fact sheets in the web app. It does not select a request for an MCP client. An agent or connector still sends proposals through its MCP tools; review the returned proposal or request items in Atlas before applying them. A person using an MCP client should check get_identity for the current write rules rather than assuming the web header selection changes the client session.

When a connection fails

Check the supported connection method, your access and the selected workspace with your administrator. Avoid placing API tokens in a prompt, an email or a shared document.

Broader access from Claude, ChatGPT, Copilot and other clients remains subject to client-by-client verification. These names describe the intended direction, not a promise that every combination is generally available today.

Read the typed workspace model

Ask your client to call pull_workspace to read the model types and stored relationships it may access. In initiative reads, initiative_type uses Idea, Program, Project or Epic as the subtype: stored Must-Win Battle becomes Program, and stored Strategic Project or Initiative becomes Project. It can request particular types, such as applications and capabilities, and leave out relationships when they are not needed. Access still comes from the connection's workspace and read permissions. Archived records are excluded where the model supports archiving, and existing financial visibility rules apply.

Check known_gaps, excluded_types and coverage before treating the result as complete. A missing owner or unsupported model field is reported; Atlas does not invent it. An empty type on one page does not mean that the workspace has no records of that type. If next_cursor is present, ask the client to continue with after and the same options, collecting pages until it is null. Changed records or access can invalidate a cursor; restart the read if that happens.

To read one record's relationships, ask your client to call get_entity_relations. It also accepts initiatives, interfaces, organizations and tech categories. A related record shows the same id whichever end you start from, with active_from, active_until and temporal_state (current, planned, planned_overdue or ended) on links with validity fields. An undated link is current; an ended link remains readable as history but leaves current cost and support rollups. pull_workspace states the same dates and state. A capability and a data object both show that the capability uses the data object, from either end, under fact_sheet_relations with the same dates and state. This is read only: these links cannot be edited through the tool yet.

The answer follows the published Atlas workspace schema. Existing read tools remain available. The workspace revision describes a snapshot; it is not a reservation or a guarantee that nothing can change before a later write.

For a later propose_changes call, the client can send the workspace revision as the top-level base_revision. Atlas checks this advisory snapshot before new writes. If it has changed, the client receives a conflict and the current workspace revision and should read again. It can still retry a completed request with the same idempotency key. This workspace check does not replace the existing item revision checks at approval and is not an atomic lock; a change that does not advance the recorded counts or latest update can remain undetected.

One element, one change, one search

Three read tools answer the questions an architect asks most, each in one call:

• get_fact_sheet returns one element as text, with its relationships and where each field came from (a person, an AI with review status, or a connector). If one of the three parts does not cover the element's type yet, that part says unsupported_entity_type instead of looking empty. For an application it also returns relation_explanations: each relation with its direction, where it came from (a person, an import, a connector, an AI, or unknown), short evidence excerpts and what is not known. A confidence appears only where a model stored one, and missing evidence or origin is named, not left empty. See Sources and evidence for what each code means.
• get_impact answers "what happens if we change this application": the affected applications and why, the capabilities, the owners to involve, and what is unknown, such as a missing owner. It uses the same function as the change-impact page, so the client and the web app show the same facts. It covers applications today.
• search finds records and decisions by keyword. Decisions are matched on what they say, not only their title. Use the types list to narrow it.

get_dataset also offers ai_governance_v1 (the AI governance numbers, one row per metric) and ai_registry_v1 (the registered AI agent systems, one row each). architecture_policies_v1 lists principles, standards and patterns with their statements and rationale. policy_exceptions_v1 lists each exception with its policy, affected entity, approval status and linked decision. Only approved means approved; inactive policies remain visible with is_active: false. Both datasets use your connection's workspace. All of this is read only.

Check the model before you change it

Ask your client to call audit_workspace to check the workspace against Atlas' 27 audit rules: missing owners and classifications, lifecycle dates out of order or past end of life, broken interfaces, personal data without classification, gaps in the capability hierarchy, strategy and decision loose ends, and AI systems without an owner. Each finding names the element, the rule and what to do about it. The rules are listed in the published catalog.

The client can pass the same changes it would send to propose_changes. Atlas then audits the model as it would look with those changes, without writing anything, so you see what a change request would break before it is submitted. Check known_gaps: a rule the model cannot evaluate yet is listed there instead of passing silently.

Try a first analysis or follow the workflow from source to proposal.

Use Draft a landscape from sources to prepare a first batch, and Validate changes and inspect quality to check it.

Read application fit scores

The existing applications_v1 dataset returns business_fit_score and technical_fit_score as numbers from 0 to 10 or null when no score is recorded. A missing score is not a zero. Compare those values with the saved TIME decision when checking a report's score-based position.