c25 Item-Type Connection Research

Saved: 2026-04-22 Purpose: Keep a reusable reference for how each c25 item-map should connect in synthetic data.

Source Notes

The most stable primary-source facts I used:

• MCP uses a host -> client -> server architecture, and servers expose tools, resources, and prompts. Servers can back those primitives with files, APIs, and databases. Source: Model Context Protocol architecture overview
• OpenAI Agents SDK defines an agent as an LLM configured with instructions, a model, and tools. Source: OpenAI Agents SDK: Agents
• OpenAI Agents SDK sessions are persistent conversation state passed into agent runs. Source: OpenAI Agents SDK: Sessions
• OpenAI tool calling is a multi-step flow where the application provides tools, the model emits tool calls, the application executes them, and then returns tool outputs back to the model. Source: OpenAI Function Calling guide
• OpenAI Responses API requests go to provider endpoints and API keys are sent as Bearer auth. Sources: OpenAI API auth, OpenAI Responses API overview
• A repository contains code, files, and revision history. Source: GitHub Docs: About repositories

Interpretation Rules

These are the c25 modeling inferences I’m using on top of the sources above:

• Model is treated as a logical capability selected by runtimes, not as the network caller itself.
• Endpoint is treated as the network boundary that callers reach over HTTP.
• API Key is treated as a credential mounted into callers and used to authorize endpoint access, not as a child of a model.
• Tool is treated as callable capability surface. It can be local/runtime-defined, MCP-exposed, or backed by repo/file/API work.
• Session is treated as run/conversation state and orchestration context, not as the owner of every downstream infrastructure edge.

Direct Connection Guidance

Session

Prefer direct edges to:

• User
• AI Agent
• Model
• MCP Server
• Tool
• Sub-Agent
• Secondary Call

Avoid making Session the direct caller of:

• Repository
• File
• Endpoint
• API Key

Those are better shown through agent/tool/MCP context unless a specific runtime truly owns them.

AI Agent

Prefer direct edges to:

• Session
• Model
• MCP Server
• Tool
• Sub-Agent
• Repository
• Secondary Call

Usually avoid direct edges to:

• User when a Session already captures that relationship
• API Key unless the map is specifically about credential mounting
• File when the repository is the better work-surface abstraction

User

Prefer direct edges to:

• Session

Everything else is usually downstream context through sessions and agents.

MCP Server

Prefer direct edges to:

• AI Agent
• Session
• Tool when the tool is exposed by the server
• backing systems such as Repository, File, or Endpoint

This matches MCP’s role as a context/action provider between host runtimes and external systems.

Model

Prefer direct edges to:

• consuming AI Agent nodes
• consuming Session nodes

Treat these as contextual, not direct, unless a specific implementation proves otherwise:

• Endpoint
• Tool
• Repository
• File

Important c25 inference:

• the network caller is typically the agent/runtime hitting a provider endpoint with a chosen model, so the model page should mostly read as consumer concentration.

API Key

Prefer direct edges to:

• systems that hold or load the key, such as AI Agent or MCP Server
• provider Endpoint nodes that the key authorizes

Avoid treating the key as directly attached to:

• Model

unless the graph is explicitly modeling provider-level configuration rather than request execution.

Endpoint

Prefer direct edges to:

• AI Agent
• MCP Server
• API Key

Optional:

• Session only when the session runtime itself is clearly the HTTP caller

Tool

Prefer direct edges to:

• AI Agent
• Session
• MCP Server when the tool is server-backed
• concrete work surfaces it touches, such as Repository, File, or Endpoint

Avoid artificial direct tool -> model edges.

Repository / File

Prefer direct edges to:

• AI Agent
• Tool
• MCP Server
• Sub-Agent
• File membership under Repository

Prefer repository-first maps over file-first maps when possible, because the repository is the higher-level work surface.

Secondary Call

Prefer direct edges to:

• parent Session
• parent or owning AI Agent
• Model
• Tool
• Repository
• File
• Endpoint only if that nested task actually makes network calls

Practical c25 Defaults

For item-centric maps, default to:

• one focal actor of the selected item type
• multiple surrounding actors of other types when the real-world topology is fan-in or fan-out
• entity-type grouping first
• second-hop context instead of fake direct edges whenever possible

Follow-up Candidates

• Add an explicit Credential Mount or Secret Store entity type if API key topology needs more precision.
• Add Resource as a first-class c25 type if MCP-backed context starts to matter as much as tools.
• Split Tool and Skill if local runtime tools and MCP-exposed tools keep reading differently.