Give Your AI Agent the Context of Your IT Landscape

Your AI coding agent reads the repository it works in, and nothing else. It does not know that three other applications consume the field it is about to rename, that the ERP calls the service it is about to remove, or which team owns the system it is opening a ticket for. So it guesses, and a confident guess about architecture is how a routine change becomes an incident. Architecture context has become a resource you give your agents on purpose, like an API key or a coding standard.

TL;DR

• Agents such as Claude Code, Cursor or Codex see the code in front of them, not the IT landscape around it: consumers, owners, hosting, business processes.
• You can give them that context through repo files, wiki pages, or an MCP server connected to an architecture repository. Only the last one is shared across repos and stays queryable.
• Good context answers five questions: what is this system, who exchanges data with it, who owns it, where does it run, which processes depend on it.
• Ask for read-only by default, one token per organisation and every call audited.
• UrbaHive exposes its repository through an MCP server, on every plan including the free one.

What does your AI agent not know about your IT landscape?

Your agent knows the code it can open and nothing about the systems that code talks to. Beyond the repository boundary, it has no source and fills the gap with plausible text.

• Renaming a field. The agent cleans up the customerRef field in an order service: service, tests and OpenAPI file updated. Nothing in the repo says that billing, the data warehouse and a partner portal read that field from an export. Three consumers break in production.
• Decommissioning a service. The agent deletes a "legacy" pricing service with no callers in the monorepo. The ERP calls it every night through a batch flow nobody described in the code. The first sign is a failed invoicing run.
• Routing work to the wrong team. An ops agent assigns an incident ticket to whoever committed last. The application's actual owner, and the vendor contact who could fix it, are recorded nowhere the agent can see.

None of these are model failures. What is missing is the landscape (which applications exist, how they exchange data, who answers for them), which is why living architecture documentation is built on data rather than drawings. An agent can query data; it cannot read a stale diagram.

What are the three ways to give an agent architecture context?

You can put context in the repository, in a wiki, or behind an MCP server connected to an architecture repository. They are not exclusive, but they do not cover the same ground.

The practical rule: keep code-level context in the repo (module boundaries, conventions, how to run the tests) and serve landscape-level context from one shared repository. An ARCHITECTURE.md that lists every consumer of every API will be wrong within a quarter, and each repo will hold its own version of the truth.

MCP (Model Context Protocol), an open standard for calling tools on an external server, lets the agent query the repository when it needs the answer instead of relying on a copy pasted weeks ago.

What should good architecture context contain?

Good architecture context answers the five questions below for any system the agent touches. Anything finer (endpoints, field names, schemas) belongs in the code and its contracts.

Two details matter more than volume. Direction: "B consumes a nightly export from A" tells the agent who breaks if A changes; "A talks to B" does not. A named person: a team alias does not answer "who do I ask before I merge this". If ownership is your weak spot, start with an application ownership matrix.

Be clear about granularity too. The repository knows that billing receives a flow from the order service, not that the flow carries customerRef. The agent combines both: the map says which consumers to check, the code and contracts say what each one reads.

Beyond one product and a couple of repos, a shared repository pays off: UrbaHive's free plan (1 user, 25 applications, no credit card) is enough to connect an assistant to a first map.

How do you connect an agent to your architecture data safely?

Use a token scoped to one organisation, read-only unless you decide otherwise, and logged on every call: ask that of any MCP server. UrbaHive's connector, as a reference:

• One token per organisation. A personal access token reaches a single organisation, even if the user belongs to several.
• Read by default, write on purpose. The connector has 74 tools: 32 read, 42 write. A token is read-only unless the write scope was enabled at creation, and writing also requires a sufficient role.
• No tool can delete an application, a flow or any other object of the map. The only destructive tool removes a custom-field definition; it is reserved to the organisation's owner and needs a two-step confirmation.
• Rate limit and audit. 60 requests per minute per token; every call goes to the audit log, alongside every change made in the app.
• Hosting. Data is hosted in European Union regions, encrypted in transit and at rest.

One limit to state to your security team: what the agent reads is sent to the assistant's provider and processed under its terms, separately from the repository. Choose which assistant your organisation approves and keep personal data out of free-text descriptions. The MCP security and GDPR article covers the usual CISO objections.

Which questions can your agent answer from the map?

Any question the map's data can answer: inventories, flows, hosting, owners, processes, capabilities, plus a search across the repository and a landscape summary. It cannot invent what was never recorded.

Two habits make answers reliable. Ask for sources: "list the flows you used" turns a fluent paragraph into something you can check in the app. Write the check into the agent's instructions: a line in CLAUDE.md, AGENTS.md or your Cursor rules such as "before renaming or removing anything that leaves this service, query UrbaHive for this application's flows and owners" makes it part of the change.

Know the limits: the answer is only as current as the map, and an undocumented flow will not appear. Chained reads rebuild dependencies from documented data only, which is why a dependency-first decommissioning checklist still requires a human sign-off. More scenarios in the MCP enterprise use cases.

How do you set it up?

Generate a token, paste a short configuration into your assistant, ask a first question: a few minutes if the map already has data.

1. In UrbaHive, open Settings → Connectors and generate a token for the target organisation, write disabled for a first test.
2. Add the UrbaHive MCP server to your client (Claude Desktop, claude.ai, Claude Code, Cursor, Windsurf, Codex or Devin). The Claude tutorial and the per-client configurations give the exact snippets.
3. Ask "Summarise my IT landscape in five points", check the answer, then add the instruction above to your agent's project rules.

If the map is still empty, a write token lets an agent bootstrap it from your code; you then review what it created.

FAQ

Is it safe to connect an AI assistant to my architecture data?

It is reasonable if the connector is read-only by default, scoped to one organisation and audited, and if your organisation approves the assistant: what the assistant receives is processed by its provider. With UrbaHive, a token reaches one organisation, every call is logged and data is hosted in the EU.

Can the agent modify my map?

Only if you allow it: a token is read-only unless the write scope was enabled at creation, and writing requires a sufficient role. Even then, no tool can delete an application, a flow or any other object of the map; the one destructive tool removes a custom-field definition, is reserved to the owner and needs a two-step confirmation.

Which assistants are supported?

Claude Desktop, claude.ai, Claude Code, Cursor, Windsurf, Codex and Devin, each with a documented configuration.

Does it work on the free plan?

Yes. Every plan includes the MCP connector; only quotas differ. The free plan covers 1 user and 25 applications, with no credit card and no time limit.

Give your agents the map, not a guess

Coding and ops agents act on whatever context they have. For mid-sized organisations (50 to 5,000 employees), a shared repository of applications, flows, owners and processes is the cheapest way to make that context accurate. Connect your AI assistant on the free plan: 1 user, 25 applications, no credit card. Create your UrbaHive account.