MCP Resources

MCP resources are data that the client can pre-load into the conversation before the agent starts working. Unlike tools, which the agent invokes on demand, resources are fetched by the client and injected into the context window automatically or on request.

Contextia exposes two resources:

Resource URI	Purpose	Typical loading
contextia://identity	Project identity and key norms	Always loaded
contextia://index	Navigation map of all artifacts	On demand

contextia://identity

URI: contextia://identity

This resource provides the project’s identity — its name, purpose, tech stack, key norms, and anything else that an AI agent needs to understand before doing any work. It is sourced from .contextia/system/identity.md.

Why it exists

Every AI agent interaction starts with a question: “What project am I working on?” Without this context, the agent makes assumptions about language, framework, conventions, and architecture that may be wrong.

The identity resource answers this question definitively. It is designed to be loaded at the start of every conversation, giving the agent a grounding document that shapes all subsequent decisions.

What it contains

The identity resource returns the full content of identity.md, which typically includes:

---
project: my-project
version: "1.0"
---

# My Project

## What this project is
A REST API for managing inventory in retail stores, built with
FastAPI and PostgreSQL.

## Tech stack
- Language: Python 3.12
- Framework: FastAPI 0.109
- Database: PostgreSQL 16 with asyncpg
- ORM: SQLAlchemy 2.0 (async)
- Testing: pytest + httpx

## Key norms
- All endpoints return JSON with envelope: { data, error, meta }
- Database migrations use Alembic. Never modify tables directly.
- Authentication uses JWT with RS256 signing.
- All public functions have type annotations and docstrings.

## Architecture
Three-layer architecture: routes → services → repositories.
No direct database access from route handlers.

When it is loaded

MCP clients can mark resources as “always loaded,” meaning the resource content is fetched and included in the system prompt at the start of every conversation. The contextia://identity resource is designed for this pattern.

In practice, loading behavior depends on the client:

• Claude Code loads resources marked as important at session start.
• Cursor may require the user to reference the resource explicitly.
• Other clients vary in their resource handling.

Regardless of client behavior, the identity resource is small (typically under 500 tokens) and should always be loaded. It is the single most impactful piece of context for agent accuracy.

Tip

Keep your identity.md concise. It is loaded into every conversation, so every token counts. Put detailed specifications in separate spec files and link to them from identity.

How agents use it

Once the identity resource is loaded, the agent knows:

• What language and framework to use when writing code.
• What architectural patterns to follow.
• What conventions to apply (naming, error handling, response formats).
• What tools and libraries are available.

This eliminates an entire class of agent errors — using the wrong language, importing unavailable libraries, violating project conventions — without requiring the agent to search for this information.

contextia://index

URI: contextia://index

This resource provides a navigation map of every artifact in the .contextia/ directory: specs, decisions, norms, and tasks, with their IDs, titles, types, statuses, and link relationships.

Why it exists

An agent working on a task needs to know what artifacts are available before it can decide which ones to load. Without an index, the agent must either call mcp_list for each type or guess artifact IDs.

The index resource gives the agent a complete map in a single read, enabling it to make informed decisions about which artifacts to load in full.

What it contains

The index resource returns a structured listing of all artifacts, organized by type:

# Contextia Index

## Specs (12)
- SPEC-001: Project Identity Schema [approved] → links: NORM-001
- SPEC-002: Config File Format [approved] → links: DEC-001
- SPEC-003: Frontmatter Validation Rules [approved] → links: NORM-002, NORM-003
- SPEC-012: User Authentication Flow [approved] → links: DEC-003, NORM-001
- SPEC-018: API Key Authentication [draft] → links: SPEC-012
...

## Decisions (8)
- DEC-001: YAML 1.2 over TOML [accepted] → links: SPEC-002
- DEC-003: OAuth with PKCE over session cookies [accepted] → links: SPEC-012
- DEC-006: Dual CLI + MCP interface [accepted]
...

## Norms (5)
- NORM-001: Security Requirements [active]
- NORM-002: Error Handling Conventions [active]
- NORM-003: Required Frontmatter Fields [active]
...

## Tasks (6)
- TASK-042: Implement token rotation [in_progress, feature] → links: SPEC-012, DEC-003
- TASK-045: Fix session expiry race [in_progress, bug] → links: SPEC-012
- TASK-050: Add OpenAPI schema generation [backlog, feature] → links: SPEC-020
...

When it is loaded

The index is typically loaded on demand rather than always. It can be large in projects with many artifacts (50+ specs), and loading it into every conversation would waste context window space in sessions that do not need navigation.

Common loading patterns:

• At the start of a task-oriented session. The agent (or the start_feature_task prompt) loads the index to understand the landscape before diving into a specific task.
• When the agent needs to find related artifacts. If the agent is working on authentication and wants to know what other specs exist in that area, it reads the index rather than making multiple mcp_search calls.
• Never in quick one-off questions. If the user asks “What does SPEC-012 say?”, the agent calls mcp_show directly without loading the full index.

Note

The index is generated from the .contextia/.cache/ directory, which is built by scanning all artifact files. If the cache is missing, the server rebuilds it on the fly. This may add a brief delay on the first call in a session.

How agents use it

The index serves as a table of contents. Agents use it to:

1. Discover related artifacts. “SPEC-012 links to DEC-003 — I should read that decision before making changes.”
2. Check coverage. “There are 12 specs but only 6 tasks. Some specs may not have active work.”
3. Navigate by status. “Three tasks are in_progress. Let me focus on the one assigned to me.”
4. Understand link topology. “SPEC-012 is referenced by two tasks and one decision — it is a central artifact.”

Resource freshness

Both resources read from disk on each fetch. There is no caching at the MCP server level. If you update identity.md or add a new spec file, the next resource read returns the updated content.

However, MCP clients may cache resource content for the duration of a conversation. If you make changes to artifacts mid-conversation, the client’s cached copy may be stale. In this case, the agent can use tools (mcp_show, mcp_list) to get fresh data, since tools always read from disk.

Token budget considerations

Resource	Typical size	When to load
contextia://identity	200-500 tokens	Every session (always-on)
contextia://index	500-3000 tokens	Task sessions, navigation

For projects with many artifacts, the index can grow large. If the index exceeds your token budget, use mcp_list with type filters instead — it returns the same data but scoped to a single artifact type.