Skip to main content
Glama
Coinlooter

payflowagent-mcp

by Coinlooter

PayFlowAgent — MCP server & reference agent

Pay-per-call APIs for autonomous AI agents. USDC via x402, no signup.

MCP registry name: io.github.Coinlooter/mcp

This repository contains the open-source integration pieces:

Path

What

/ (root)

payflowagent-mcp — MCP server for Cursor, Claude Desktop, and custom agents.

examples/screen-bot/

Reference polling bot: finds high-score nad.fun tokens every few minutes.

The scoring APIs run on PayFlowAgent infrastructure; this repo is the client surface so agents and developers can integrate in one step.

Tools (MCP)

nad.fun (Monad)

Tool

Price

Description

score_token

free

0–100 score, riskLevel, action (rate-limited).

decide_token

x402

Full report: factors, graduation, momentum.

token_summary

x402

Graduation progress + momentum (cheap entry).

screen_tokens

x402

Ranked list of pre-scored fresh tokens.

Datafeed (DeFiLlama)

Tool

Price

Description

sample_yields

free

Top yield pools + 3-item opportunity preview (score + reasons).

yield_opportunities

x402

Ranked yield picks with risk score & explainable reasons.

Related MCP server: x402farm-mcp

Install (one line)

npx -y payflowagent-mcp@0.1.3

Use it in Cursor

~/.cursor/mcp.json (or project .cursor/mcp.json):

{
  "mcpServers": {
    "payflowagent": {
      "command": "npx",
      "args": ["-y", "payflowagent-mcp@0.1.3"],
      "env": {
        "PAYFLOWAGENT_API_BASE": "https://nad.payflowagent.net",
        "PAYFLOWAGENT_DATAFEED_BASE": "https://data.payflowagent.net"
      }
    }
  }
}

Use it in Claude Desktop

Same config as Cursor (Settings → Developer → MCP Servers).

Without X402_BUYER_PRIVATE_KEY only free tools work (score_token, sample_yields). Use a dedicated payer wallet (Base, USDC) — never your main wallet.

Configuration (env)

Variable

Default

Purpose

PAYFLOWAGENT_API_BASE

https://nad.payflowagent.net

nad.fun API base URL.

PAYFLOWAGENT_DATAFEED_BASE

https://data.payflowagent.net

Datafeed API base URL.

X402_BUYER_PRIVATE_KEY

Payer wallet key (Base, USDC). Enables paid tools.

X402_BUYER_RPC

https://mainnet.base.org

Payment RPC (optional).

MCP Registry

After npm publish, list in the official registry:

npm install -g @modelcontextprotocol/publisher
cd payflowagent-mcp
mcp-publisher login github
mcp-publisher publish

Manifest: server.json (io.github.Coinlooter/mcp).

Reference agent

See examples/screen-bot — polls /v1/screen every few minutes, de-duplicates, and alerts on new high-score tokens (optional webhook). Fork it and point it at your own trading logic.

Develop locally

npm install
npm run typecheck
npm run build      # emits dist/
npm start          # stdio server from source (tsx)

Publish to npm

npm run build
npm publish

License

MIT — see LICENSE.

Available Tools

6 tools
decide_tokenVoller Report (bezahlt, x402)A

Bezahlt (USDC via x402). Entscheidungsfertiger Report fuer einen nad.fun-Token: Score, riskLevel, action, erklaerende Faktoren, Graduation-Fortschritt und 5-Minuten-Momentum.

ParametersJSON Schema
NameRequiredDescriptionDefault
tokenYes

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the key behavioral trait of payment (USDC via x402), which is critical for a paid tool. However, it lacks details on the payment process, error handling, or rate limits, making it good but not fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief (two sentences) and front-loaded with the payment aspect, efficiently communicating the tool's value. No redundant content, but the mixed language (German/English) could confuse some users.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lists the report components (score, riskLevel, action, etc.), providing essential return context. However, without an output schema, more details on format or interpretation would improve completeness. It adequately covers the main outputs but lacks precision.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and description does not explain the 'token' parameter at all, missing an opportunity to add context (e.g., Ethereum address format for nad.fun tokens). The schema alone provides the pattern, but the description should compensate for the lack of parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides a decision-ready report for a nad.fun token, listing specific outputs (score, riskLevel, action, etc.) and notes it is paid (Bezahlt). This distinguishes it from siblings like score_token (simple score) or token_summary (likely free), using a specific verb-resource combination.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when a paid comprehensive report is needed, but does not explicitly state when to use versus alternatives. It mentions payment but no when-not or direct comparison to siblings, leaving usage context implicit rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

sample_yieldsYield-Sample (kostenlos, Datafeed)A

Kostenloser, rate-limitierter Datafeed-Probe: Top DeFi-Yield-Pools plus 3-item Opportunity-Vorschau (Score 0-100 + erklaerbare Gruende). Ideal vor einem bezahlten yield_opportunities-Aufruf.

ParametersJSON Schema
NameRequiredDescriptionDefault
chainNoChain-Filter, z. B. Base, Ethereum
limitNoMax. Pools in der APY-Liste (1-5, Default 5)
profileNoRisiko-Preset fuer die Vorschau (Default stable)

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses rate-limiting and free nature, but with no annotations provided, it lacks detail on read-only status, authentication needs, or side effects. Acceptable for a simple datafeed sample, but could be improved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: the first explains what the tool does and returns, the second states its ideal use case. No redundancy, perfectly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Provides enough context for a simple tool: explains output (top pools plus 3-item preview with scores/reasons), mentions rate limit, and references the paid alternative. Missing mention of ordering or data freshness, but adequate for its purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all parameters with descriptions (100% coverage). The tool description adds no additional parameter-specific details beyond the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool provides a free, rate-limited sample of top DeFi yield pools plus a 3-item opportunity preview with scores and reasons. It explicitly distinguishes itself from the sibling 'yield_opportunities' as a free precursor, using specific verbs and resource names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Ideal vor einem bezahlten yield_opportunities-Aufruf' (Ideal before a paid yield_opportunities call), indicating when to use this tool. While it doesn't exclude other siblings, the context is clear for its primary role as a free trial.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

score_tokenToken-Score (kostenlos)A

Kostenloser, rate-limitierter Score (0-100) inkl. riskLevel und action fuer einen nad.fun-Token auf Monad. Ideal zum Pruefen vor einem bezahlten Aufruf.

ParametersJSON Schema
NameRequiredDescriptionDefault
tokenYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description discloses rate-limited and free nature, but does not discuss authentication, error handling, or the meaning of 'action' output. Partially compensates for missing annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence efficiently conveys purpose, constraints, and output components. No superfluous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers main purpose and outputs but omits details on rate limit specifics, output format, and semantics of riskLevel/action. Adequate for a simple tool given lack of output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Single parameter 'token' with regex for Ethereum address, but schema description coverage is 0%. The description only says 'nad.fun-Token auf Monad' without elaborating on the token address format or constraints, leaving ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides a free, rate-limited score (0-100) with riskLevel and action for a nad.fun token on Monad, distinguishing it from paid alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'Ideal zum Pruefen vor einem bezahlten Aufruf' (ideal for checking before a paid call), giving context on when to use. Lacks explicit when-not or alternative tool mentions, but siblings suggest decision tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

screen_tokensScreening: gerankte Token-Liste (bezahlt, x402)A

Bezahlt (USDC via x402). Gerankte Liste vorgescorter, frischer nad.fun-Token (score, riskLevel, action, Graduation, Holder). Ideal fuer Screener/Trading-Agenten, die regelmaessig nach Chancen suchen.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax. Anzahl Token (1-25, Default 10)
minScoreNoNur Token mit Score >= minScore (0-100)

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that the tool is paid (USDC via x402), which is critical behavioral info. However, it does not explain any other behaviors such as caching, rate limits, or whether the list is always fresh. With no annotations, the description carries the full burden but leaves gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the most important information (paid, ranked list). No unnecessary words. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately lists the fields in the returned list. Parameters are simple. Context for usage as a regular screening tool is provided. Could be more specific about exact structure, but sufficient for the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers both parameters with descriptions (100% coverage). The description adds value by mentioning the output fields (score, riskLevel, etc.), helping to interpret the effect of minScore. This goes beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns a ranked list of prescreened tokens with fields like score, riskLevel, action, etc. It specifies it is ideal for screening/trading agents. However, it does not explicitly differentiate from sibling tools like score_token or token_summary, which focus on single tokens rather than lists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions it is ideal for regular opportunity scanning agents, giving a usage context. But it lacks explicit guidance on when not to use it or how it compares to alternatives like sample_yields or yield_opportunities.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

token_summaryGraduation + Momentum (bezahlt, x402)C

Bezahlt (USDC via x402). Guenstiger Einstieg: Graduation-Fortschritt (Bonding-Curve %) + Momentum-Zusammenfassung fuer einen nad.fun-Token.

ParametersJSON Schema
NameRequiredDescriptionDefault
tokenYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided. The description mentions 'Bezahlt (USDC via x402)' suggesting a paid operation, but it does not elaborate on cost, authentication, rate limits, or any side effects. The tool's behavior beyond the returned summary is completely opaque.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short, consisting of two sentences. The first sentence 'Bezahlt (USDC via x402)' is cryptic and not explained, reducing clarity despite conciseness. The second sentence is clear but the structure is front-loaded with unclear information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description should provide comprehensive context. It mentions the output covers graduation progress and momentum, but does not specify the format, example values, or any additional details about the token. Given the tool appears to be paid, crucial usage context is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one parameter (token) with 0% description coverage. The description mentions 'einen nad.fun-Token' which implies the token must be from nad.fun, but it does not explicitly describe the parameter or its format. The schema's regex pattern is not reinforced or explained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool provides graduation progress (bonding curve percentage) and momentum summary for a nad.fun token. The verb is implied but clear from context. The phrase 'Guenstiger Einstieg' adds usage context. However, the title includes 'bezahlt' and 'x402' which are not explained in the description, slightly reducing clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus sibling tools (decide_token, score_token, etc.). The description does not mention prerequisites, alternatives, or exclusion criteria. The term 'Guenstiger Einstieg' hints at a use case (cheaper entry), but it is not explicit about when to prefer this tool over others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

yield_opportunitiesYield-Opportunities (bezahlt, x402, Datafeed)A

Bezahlt (USDC via x402). Gerankte DeFi-Yield-Chancen mit Score (0-100), Rank und reasons[] — agent-tauglich, nicht nur APY-Sortierung. Profile: stable (Default), balanced, aggressive.

ParametersJSON Schema
NameRequiredDescriptionDefault
chainNoChain-Filter, z. B. Base
limitNoMax. Ergebnisse (1-25, Default 10)
minApyNoMindest-APY in %
minTvlNoMindest-TVL in USD
stableNoNur Stablecoin-Pools
profileNoRisiko/yield-Preset (Default stable)

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses payment via x402 and agent-suitability, which adds value beyond schema. However, no annotations exist, so description should cover more behavioral traits like data freshness, rate limits, or side effects; it omits these.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with key info front-loaded (payment, functionality, risk profiles). No wasted words, but could be slightly more structured for complex tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description mentions return fields (score, rank, reasons) but lacks exact structure or format. Parameters explained in schema fill gaps, but overall completeness is average.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all 6 parameters with descriptions (100% coverage). Description adds little beyond schema, only reiterating profile enum and scoring concept. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it provides ranked DeFi yield opportunities with score, rank, and reasons, distinguishing it from siblings like 'sample_yields' or 'screen_tokens' which may focus on different aspects. The verb 'bietet' (provides) and resource 'DeFi-Yield-Chancen' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage for scored ranking beyond APY sorting and mentions risk profiles, but lacks explicit guidance on when to use vs alternatives like 'sample_yields' or 'decide_token'. No 'when not to use' mention.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.1.3
    • First observeddecide_token
    • First observedsample_yields
    • First observedscore_token
    • First observedscreen_tokens
    • First observedtoken_summary
    • First observedyield_opportunities

TDQS

B3.4/5.0

Scored across 6 tools

Disambiguation4/5

Tools are mostly distinct with clear paywall segregation. However, decide_token, score_token, and token_summary all target a single token with overlapping information, risking confusion if descriptions are not read carefully.

Naming Consistency3/5

Naming pattern is mixed: four tools use verb_noun (decide_token, sample_yields, score_token, screen_tokens) while two use noun_noun (token_summary, yield_opportunities). Also, pluralization varies (yields vs. token/tokens).

Tool Count5/5

Six tools is an appropriate size for a DeFi analysis server, covering both token and yield domains without being overwhelming or sparse.

Completeness4/5

Core token analysis (score, summary, full report, screening) and yield opportunities (sample and full) are covered. Minor gaps like drill-down on a specific yield opportunity exist, but the surface is adequate for the stated purpose.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers