Technical documentation
Architecture
Understand how ROUTE connects MCP clients to opportunity services, provider integrations, and persistent saved-opportunity state. This page describes the current architecture and distinguishes implemented capabilities from future directions.
Scope
BoundaryA shared opportunity infrastructure layer
ROUTE is an agent-agnostic MCP server. It exposes focused tools for discovering opportunities, retrieving details, saving opportunities, and gathering preparation context. The connected agent or application remains responsible for its own reasoning, user experience, and higher-level workflow orchestration.
Architectural boundary
ROUTE supplies opportunity capabilities through MCP. It is not itself the conversational agent, and the current implementation should not be treated as an autonomous application-submission or opportunity-tracking system.
Architecture concepts
5 conceptsROUTE separates the client-facing protocol interface from opportunity operations, external data sources, and persistent state. Each part has a distinct responsibility.
System participants
MCP client and agent
Discovers available tools, supplies arguments, receives results, and decides how to use the returned information.
ROUTE MCP server
Exposes the opportunity tools and coordinates their execution through application services.
Opportunity providers
Interact with supported external sources and convert source-specific information into ROUTE's common opportunity representation.
Persistent state
Supports saved-opportunity data independently of the external platforms from which opportunities are discovered.
System layers
- Layer 01
MCP interface
Exposes ROUTE capabilities as tools that compatible MCP clients can discover and invoke.
- Layer 02
Opportunity services
Coordinates opportunity operations and delegates provider-specific work to the provider manager.
- Layer 03
Provider layer
Resolves supported opportunity sources, retrieves source data, and normalizes results into a shared model.
- Layer 04
Persistence
Stores saved opportunity state separately from the external sources used to discover opportunities.
MCP transport layer
ROUTE uses the Model Context Protocol to expose tools to compatible clients. Its configured HTTP transport is Streamable HTTP, which carries MCP communication between the client and server.
The transport provides the communication channel. The opportunity tools define the operations available through that channel.
Opportunity data model
Providers normalize their source data into a common opportunity representation. This reduces the need for clients to understand each external platform's individual data structure.
idIdentifies the normalized opportunity.
titleThe opportunity's displayed title.
typeThe current category, such as job or hackathon.
organizationThe organization associated with it.
descriptionAvailable descriptive information.
urlThe opportunity's canonical destination.
sourceIdentifies the provider or originating source.
sourceUrlIdentifies the source endpoint or reference.
Optional fieldsMay include location, remote status, deadline, prize, and metadata.
Optional fields depend on the data supplied by the source. Normalization does not guarantee that every provider has every field.
Provider architecture
Provider-specific behavior belongs behind a shared provider interface. The opportunity service delegates retrieval to the provider manager rather than embedding source-specific parsing logic in each MCP tool.
Opportunity service
Coordinates the requested operation and delegates source resolution.
Provider manager
Determines which provider can handle the opportunity or request.
Source provider
Fetches and parses source-specific data, then returns a normalized opportunity.
Request lifecycle
4 stages · 4 operationsA request begins with an MCP client, passes through the relevant ROUTE tool and service, and returns a structured result. The exact execution path depends on the tool being called.
- 01
Client request
An MCP client invokes a ROUTE tool with the arguments required for the operation.
- 02
Tool validation
The tool validates its inputs and routes the request to the appropriate application service.
- 03
Service and provider
The service coordinates the operation. For source-backed operations, the provider layer handles source-specific retrieval and normalization.
- 04
Structured result
ROUTE returns the operation result to the MCP client, which makes the information available to its connected agent or application.
Discovery
The client invokes search_opportunities with supported search criteria. ROUTE queries the relevant providers, normalizes returned records, and provides results for the connected agent to evaluate.
Retrieval
The client can invoke get_opportunity to retrieve an individual opportunity by its supported reference, such as its URL. The service delegates source resolution and retrieval to the provider layer.
Saving
The save_opportunity tool handles saving an opportunity for later use. This operation concerns ROUTE's saved-opportunity state rather than creating or modifying a listing on the original external platform.
Preparation
The prepare_opportunity tool retrieves the main preparation context available for an opportunity. Planned preparation sub-tools can expand the information collected from relevant pages and resources. The connected agent can use the returned context to help a user understand requirements and plan next steps.
Tool execution flow
4 stepsROUTE keeps MCP tool handlers focused on accepting requests and returning results, while application services and providers own the relevant operation logic.
- 01
The MCP client selects a tool and supplies its arguments.
- 02
The tool validates the arguments and invokes the appropriate operation.
- 03
The service coordinates provider retrieval or saved-state operations as required.
- 04
The result is returned to the MCP client for use by the connected agent or application.
This separation makes it possible to extend source support without making every MCP tool responsible for every external platform. Each tool should still have a clear contract, validated inputs, and predictable output behavior.
Persistence
Saved statePersistence and saved opportunities
External opportunity listings and ROUTE's saved-opportunity records serve different purposes. External sources provide the listings; ROUTE's persistence layer stores the saved state needed by its own capabilities.
External opportunity data
Retrieved from supported sources. Its availability and completeness depend on those sources.
Saved-opportunity state
Stored separately to support saving and retrieving opportunities within ROUTE.
ROUTE uses DynamoDB for persistent state. A production deployment must configure the required AWS resources and permissions. Authentication, user-to-agent identity mapping, and access isolation must be designed and verified separately before assuming saved records are securely scoped to individual users.
Extensibility
4 stepsExtending ROUTE
ROUTE is designed to grow through new providers and focused capabilities while preserving the common opportunity interface.
- 01
Add a provider
Implement the shared provider contract for a new external source, including its supported lookup, search, and preparation behavior.
- 02
Normalize the source
Map source-specific fields into the common Opportunity model and preserve source references needed for retrieval.
- 03
Connect the capability
Integrate the provider through the provider manager and relevant services rather than embedding source-specific logic in the MCP tool.
- 04
Test the full path
Verify source parsing, normalization, tool behavior, failure handling, and any persistence requirements before documenting the capability as implemented.
Current scope and future direction
Implemented · PlannedThe architecture is designed to support broader opportunity workflows, but the documentation should distinguish what is implemented now from what remains planned.
Current capabilities
- Opportunity discovery and retrieval
- Saving opportunities
- Main opportunity preparation context
- Provider-based normalization
- MCP access through Streamable HTTP
Future directions
- Deeper preparation sub-tools
- Additional opportunity categories and providers
- Expanded workflow and progress tracking
- Agent orchestration and longer-running workflows
- Additional integrations and deployment hardening
The current/future distinction should be updated as features are implemented and tested. The presence of an architectural extension point does not mean a corresponding user-facing capability is already available.