[DMP 2026]: Finternet: MCP Server for UNITS API — Agentic Tooling and Gap Remediation

[vineet-finternet]

Ticket Contents

Description

The Model Context Protocol (MCP) is rapidly becoming the standard integration layer for AI agents interacting with external services. Finternet's UNITS system — with its delegation-scoped account model, programmable token operations, and credential-gated transfers — is a natural fit for agentic execution: recurring payments, conditional transfers, cross-border routing, and portfolio operations all benefit from agent-driven automation without requiring real-time user approval per operation.
An initial MCP server for the UNITS API exists but has known gaps in tool coverage, error handling, and agentic workflow support. This project has two workstreams: (1) audit and remediate existing MCP server gaps, and (2) design and implement delegation-scoped agentic workflow tools that expose UNITS' programmable delegation model to AI agents in a safe, policy-bound way.

Goals & Mid-Point Milestone

Goals

• Workstream 1 — Conduct a systematic audit of the existing UNITS MCP server against the full UNITS App API surface. For each gap, produce one of:
  • A new MCP tool implementation
  • A documented limitation with rationale (e.g., operations that should not be exposed via MCP for security reasons)
  • A fix to an existing tool (error handling, schema correctness, response formatting)
• Workstream 2 — Design and implement MCP tools that expose UNITS' delegation model to agents safely. All agent-initiated operations must present a valid delegation credential chain; UNITS enforces scope at execution time. Tools to implement:
  • get_account_summary — returns unified token holdings (native + proxy), active delegations, and credential store summary for the delegating account; respects delegation scope
  • initiate_transfer — initiates a token transfer within the agent's delegated scope (token class, amount limit, frequency limit enforced); returns pre-flight policy evaluation result before committing
  • check_transfer_eligibility — dry-run transfer policy evaluation without committing; returns which dependency pointers passed/failed and which credentials were checked
  • get_delegation_scope — returns the agent's current delegation credential with scope constraints; allows an agent to self-check before attempting an out-of-scope operation
  • subscribe_lifecycle_events — subscribes the agent to UNITS lifecycle events (transfer committed, credential expired, dependency pointer state changed) relevant to the delegating account, within delegated scope
  • present_credential_vp — constructs and submits a Verifiable Presentation from the account's credential store to satisfy a transfer policy credential requirement; agent does not see raw credential values
• Agentic safety constraints:
  • No MCP tool may expose a raw private key or credential claim value to the agent
  • initiate_transfer always returns a pre-flight eligibility check result before committing; agents cannot skip the pre-flight
  • All tool calls are logged with the agent's Finternet account address
  • Scope violations return a structured SCOPE_EXCEEDED error, not a generic failure
• Goals Achieved By Mid-point Milestone: get_account_summary, check_transfer_eligibility, and get_delegation_scope tools implemented and tested.

Setup/Installation

Builds on the existing UNITS MCP server codebase. MCP SDK for tool definitions and server scaffolding. Local development against a Docker Compose UNITS dev environment. Integration tests using the MCP Inspector tool and a test AI agent harness (e.g., Claude via the Anthropic API with tool use).

Expected Outcome

No response

Acceptance Criteria

No response

Implementation Details

• MCP SDK: Any conformant MCP SDK may be used (reference implementations exist in TypeScript, Python, and Rust — contributor to select based on UNITS codebase language and justify the choice); all tools defined with full JSON Schema input/output specs regardless of implementation language
• Auth: All MCP tool calls carry a delegation credential chain in the request context; UNITS validates the chain before executing any operation
• Error schema: All UNITS MCP tool errors return {code: string, message: string, detail: object} where code is one of a defined enum, where code is appropriately defined enum
• Testing: Three levels required — (1) unit tests per tool against a mock UNITS server, (2) integration tests covering full request-response cycles against a dev UNITS instance, (3) end-to-end agentic workflow tests using an AI agent client exercising ≥2 complete delegation-scoped workflows. Contributor to propose specific tooling in their implementation plan.

Mockups/Wireframes

No response

Product Name

UNITS MCP Server — Agentic Tooling and Gap Remediation

Organisation Name

FinternetLabs

Domain

Financial Inclusion

Tech Skills Needed

Other

Mentor(s)

Will be assigned from the Finternet engineering team

Category

Backend, AI

[Rahul-2k4]

Hi @vineet-finternet I’m interested in working on this for C4GT 2026 and wanted to understand the contribution path a bit better before I start.

A few quick questions:

1. Which public repository contains the current UNITS MCP server implementation?
2. Are pre-application contributions/PRs welcome in that repo for this project?
3. What language is the current MCP server implemented in, or is the contributor expected to choose the implementation language?
4. Is there any existing API coverage checklist / roadmap for the current MCP server so
   contributors can identify the missing tool surface systematically?
5. Are there any public docs or repo(s) for the UNITS App API and delegation model that you recommend reading first?

I’ve started reviewing the public Finternet repos and issue details, and I’d like to align
early with the right repo and expected workflow.

Thanks.

[Varadraj75]

Hi @vineet-finternet i am interested in picking this up for C4GT 2026.
The plan is to start with a full audit of the existing MCP server against the UNITS API surface, then move into Workstream 2-get_account_summary, check_transfer_eligibility, and get_delegation_scope-to hit the midpoint milestone. I'll wire up unit → integration → e2e test coverage as I go, not after.
Before I start: which repo holds the current MCP server? Has the implementation language been decided, or is that for the contributor to justify?

[Rahul-2k4]

Hey @Varadraj75 , can u please work on some other issue , i have already been doing some work on it , so just in case not waste each other efforts . Thanks

[praveenjha527]

@Rahul-2k4 Thanks for your interest in contributing to this project for C4GT 2026. Here are the answers
to your questions:

Which public repository contains the current UNITS MCP server implementation?

• The repository is currently not public.

Are pre-application contributions/PRs welcome in that repo for this project?

• Yes, pre-application contributions and PRs are welcome.

What language is the current MCP server implemented in, or is the contributor expected to choose the implementation language?

• You are free to choose the language of your choice for the implementation.

Is there any existing API coverage checklist / roadmap for the current MCP server so contributors can identify the missing tool surface systematically?

• Yes, there is an API available for UNITS Open that you can refer to for coverage. We will publish the openapispec.

Are there any public docs or repo(s) for the UNITS App API and delegation model that you recommend reading first?

• Yes — please start with the documentation at https://docs.finternetlab.io.

[Rahul-2k4]

hi @praveenjha527 Hi @praveenjha527, thanks for the clarification.
I’ve started working through Issue #749 from the public docs and issue details, and I’m preparing a docs-based audit/ implementation plan so I can move quickly on the right surface.

Since the current MCP server repo is not public yet, could you please share the best next contribution entry point when available, whether that is:

• the MCP server repository
• the UNITS OpenAPI spec
• or any public draft interface/repo contributors should align against first

I’d like to contribute against the intended implementation surface rather than make assumptions and drift from the design.
thank you

[mn-ram]

Hi @vineet-finternet and @praveenjha527,

I've gone through the issue description carefully and explored the Finternet docs at https://docs.finternetlab.io/. I had a few specific questions before I begin structuring my implementation plan:

• For Workstream 1 (audit): once the OpenAPI spec is published, should the audit output be a structured document (e.g., a markdown table mapping each endpoint to: covered / not covered / intentionally excluded), or is there a preferred format from the Finternet team?

• For the initiate_transfer tool: the issue mentions a pre-flight eligibility check before committing. Should this pre-flight internally call check_transfer_eligibility as a reusable function, or should both tools independently call the UNITS policy evaluation endpoint?

• For language choice: is the existing (private) MCP server in TypeScript? I want to align with the existing codebase language rather than introduce a different one.

I'll begin with the docs-based audit of the UNITS API surface while the repo is being made ready.

[ChayanDass]

@vineet-finternet, @praveenjha527,
I am interested in this project as it aligns with my current interests.
I look forward to contributing.