What is MCP
The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external data sources and tools. Instead of pasting data into prompts by hand, an MCP client queries Afunana directly and pulls back program documentation, field definitions, SQL member docs, and cross-references — grounded in the same knowledge base the platform builds from the analyzed source.
Any MCP-compatible client can connect: Claude Desktop, claude.ai, Cursor, VS Code Copilot, and others. What they get is Afunana's cross-referenced map of the estate — call trees, file usage, field lineage — not a chat over a single snippet.
The MCP surface is documentation and metadata only. Raw source code is not exposed over MCP; it is available only through the authenticated REST API. See Programmatic Access Overview.
Afunana's MCP server
Afunana runs an authenticated MCP server as part of the standard backend — there is no separate process to run. The server serves the collections of the install it runs on, so the available data is scoped to that deployment. The primary platform is IBM i (COBOL/RPG/CL/DDS/SQL); the same knowledge-base contract serves Oracle collections as well, and z/OS is on the roadmap. Access over MCP is read-only and is scoped to the authenticated user's collection permissions.
Authentication
The MCP server is protected by OAuth 2.0. On first connection the client opens a browser sign-in; after the user authenticates, the client holds a token it presents on every request, scoped to that user's permissions. The sign-in uses the authorization-code flow with PKCE (S256): the client proves possession of a secret it never sends over the wire, so an intercepted authorization code cannot be replayed. Most MCP clients drive this flow automatically — the user just signs in when connecting — and discover the server's OAuth configuration through standard metadata, so there is usually nothing to configure by hand. The connection persists until the token expires, then re-authenticates.
What the assistant can query
Once connected, the assistant can retrieve, at a logical level:
- A program's documentation and metadata — its generated summary, purpose, and structure.
- Listings of programs, files, and SQL members in the collection, searchable.
- A single file's documentation and a single SQL member's documentation.
- The system overview — a narrative and structural picture of the whole codebase.
- The data dictionary and, for any field, where that field is used.
- The cross-reference / impact map — call relationships, file usage, and field references.
- The call tree — the program and file hierarchy.
There is no source-retrieval capability over MCP; raw source stays REST-only.
When a deployment serves more than one collection, the assistant can name which collection to query; otherwise it resolves to the install's collection automatically.
Connecting a client
Point your MCP-capable client at your Afunana server and complete the OAuth sign-in, following your client's own MCP-server setup steps. In practice that means adding Afunana as a custom MCP connector (claude.ai), or adding it to the MCP-server configuration of Claude Desktop, Cursor, or VS Code Copilot, and then authenticating in the browser when prompted. Use an HTTPS connection so the token is protected in transit.
Afunana also ships a dedicated VS Code extension with deeper, editor-native intelligence (hover, diagnostics, navigation, source write-back). The Copilot MCP connection is complementary — it exposes the same read-only knowledge to Copilot's own chat.
Example prompts
Once connected, ask your assistant questions like:
- "What does program ORDMAINT do?"
- "Which programs write to the CUSTMAST file?"
- "What fields are in the ORDERHDR file?"
- "Give me a system overview of this codebase."
- "Trace the field CUSTNO through every program that uses it."
The client calls the appropriate MCP capabilities and composes a grounded answer.
Security
- Every request carries the user's OAuth token, scoped to that user's permissions.
- Collection permissions apply — a user reaches only the collections they are granted.
- Read-only — no source or configuration changes are possible over MCP.
- HTTPS in production, so tokens and data are protected in transit.
- MCP activity is recorded in the backend audit trail.
Note: dynamically registered clients and in-flight authorization codes are held in memory and are not persisted across a backend restart. Active clients simply re-run the sign-in, so this is transparent in normal use — but it is why a connection may prompt for login again after a server restart.
Troubleshooting
Connection refused / timeout — confirm the server is reachable and its HTTPS certificate is valid.
Sign-in fails — confirm the username and password, that the account is active, and clear cached tokens.
No data after connecting — ensure the account has access to at least one collection, then reconnect.
"Unauthorized" during use — the token expired (or the server restarted); disconnect and reconnect to re-authenticate.