Skip to main content
Glama
Intuition MCP Server

Intuition MCP Server

Official
by 0xIntuition

Intuition MCP Server

The Intuition MCP Server is an HTTP stream server designed to interact with the Intuition knowledge graph, enabling users to query and manage data through a set of powerful tools. It provides a robust API for extracting triples, searching for entities (atoms), retrieving account information, and exploring relationships such as followers and following. This README outlines the steps to get started, the available tools, their functionalities, and instructions for running a client using the Model Context Protocol (MCP) SDK.

This repository represents the evolution of our Intuition MCP Server, which we are pleased to be open sourcing for our ecosystem. This is built upon the foundation and testing we've done. There are several contributors who helped get to this point, including francoispqt, jonathanprozzi, and simonas-notcat.

Table of Contents

Related MCP server: MCP Memory Server - HTTP Streaming

Get Started

To run the Intuition MCP Server locally, follow these steps:

Clone the Repository: Clone the project repository to your local machine:

git clone <repository-url>
cd intuition-mcp-server

Install Dependencies: Install the required dependencies using pnpm:

pnpm install

Start the Server: Launch the server using the HTTP transport (recommended):

pnpm run start:http

This will start the Intuition MCP Server, making it available at the configured host and port (e.g., http://localhost:3001). Check the server configuration for the exact URL.

Verify the Server: Once the server is running, you can test it by sending a request to the /mcp endpoint (for Streamable HTTP clients) or /sse endpoint (for legacy SSE clients). See the Running a Client (#running-a-client) section for details on connecting a client. We follow the most recent recommendations from the MCP SDK and recommend using the Streamable HTTP endpoint (/mcp) over SSE as it is in the process of being deprecated.

Note: Ensure you have pnpm installed globally (npm install -g pnpm) before running the above commands. If you encounter issues, verify that your Node.js version is 14 or higher.

Overview

The Intuition MCP Server is built to facilitate interactions with the Intuition knowledge graph, a decentralized data structure for storing and querying relationships between entities (atoms) such as accounts, concepts, and objects. The server operates as an HTTP stream server, leveraging the Model Context Protocol (MCP) to handle streaming requests and responses, making it ideal for real-time applications and large-scale data queries.

The server exposes a set of tools via API endpoints, each designed for specific tasks like extracting structured data (triples), searching for entities, retrieving account details, and exploring social connections (e.g., followers or recommendations). These tools are accessible using the MCP SDK, which supports both modern Streamable HTTP and legacy Server-Sent Events (SSE) transports for client-server communication. While we provide support for SSE, it is in the process of being deprecated in the MCP SDK, so we recommend using the Stremable HTTP endpoint.

Tools

The Intuition MCP Server provides the following tools, each with a specific purpose and input schema. All tools return responses sorted by relevance (e.g., position descending) and include detailed information, such as atom IDs and connections, to ensure comprehensive results.

Tools are registered and made available in the index.ts file.

extract_triples

Description: Extracts triples (subject-predicate-object) from user input text, enabling structured data extraction from natural language.

Input Schema:

{
  "type": "object",
  "properties": {
    "input": {
      "type": "string",
      "description": "Input from the user to extract triples from"
    }
  },
  "required": ["input"],
  "additionalProperties": false
}

Example:

Input: {"input": "Alice knows Bob"}

Usage: Extract structured triples like (Alice, knows, Bob).

search_atoms

Description: Searches for entities (accounts, things, people, concepts) by name, description, URL, or ENS domain (e.g., john.eth). Supports synonyms and keyword breakdown for flexible querying.

Input Schema:

{
  "type": "object",
  "properties": {
    "queries": {
      "type": "array",
      "items": { "type": "string", "minLength": 1 },
      "minItems": 1
    }
  },
  "required": ["queries"],
  "additionalProperties": false
}

Example:

Input: {"queries": ["ethereum", "eth"]}

Usage: Search for atoms related to Ethereum, returning at least 10 connections sorted by position, with atom IDs and detailed information.

get_account_info

Description: Retrieves detailed information about an account using its address or identifier. Falls back to search_atoms if the identifier is not a hex address.

Input Schema:

{
  "type": "object",
  "properties": {
    "address": { "type": "string" },
    "identifier": { "type": "string" }
  },
  "additionalProperties": false
}

Example:

Input: {"identifier": "0x1234567890123456789012345678901234567890"}

Usage: Fetch account details, including at least 10 connections, sorted by position, with atom IDs.

search_lists

Description: Searches for lists of entities (e.g., blockchains, crypto CEOs) by name or description, supporting complex queries broken down into simpler terms.

Input Schema:

json

{ "type": "object", "properties": { "query": { "type": "string", "minLength": 1 } }, "required": ["query"], "additionalProperties": false }

Example:

Input: {"query": "defi protocols"}

Usage: Retrieve a list of DeFi protocols, returning at least 10 items sorted by position, with atom IDs and details.

get_following

Description: Retrieves atom IDs that an account follows, optionally filtered by a predicate (e.g., follow, recommend).

Input Schema:

{
  "type": "object",
  "properties": {
    "account_id": { "type": "string", "minLength": 1 },
    "predicate": { "type": "string", "minLength": 1 }
  },
  "required": ["account_id"],
  "additionalProperties": false
}

Example:

Input: {"account_id": "0x3e2178cf851a0e5cbf84c0ff53f820ad7ead703b", "predicate": "recommend"}

Usage: List atoms recommended by the specified account.

get_followers

Description: Retrieves followers of an account, optionally filtered by a predicate (e.g., follow, recommend).

Input Schema:

{
  "type": "object",
  "properties": {
    "account_id": { "type": "string", "minLength": 1 },
    "predicate": { "type": "string", "minLength": 1 }
  },
  "required": ["account_id"],
  "additionalProperties": false
}

Example:

Input: {"account_id": "0x3e2178cf851a0e5cbf84c0ff53f820ad7ead703b", "predicate": "follow"}

Usage: List accounts following the specified account.

search_account_ids

Description: Searches for an account address using an identifier, typically an ENS address (e.g., intuitionbilly.eth).

Input Schema:

{
  "type": "object",
  "properties": {
    "identifier": { "type": "string", "minLength": 1 }
  },
  "required": ["identifier"],
  "additionalProperties": false
}

Example:

Input: {"identifier": "vitalik.eth"}

Usage: Resolve the ENS address to its corresponding account address.

Running a Client

The Intuition MCP Server uses the Model Context Protocol (MCP) SDK for client interactions, supporting both modern Streamable HTTP and legacy Server-Sent Events (SSE) transports. Below are the steps to set up and run a client to communicate with the server.

Prerequisites

Node.js (version 14 or higher).

MCP SDK: Install the @modelcontextprotocol/sdk package.

Access to the server URL (e.g., http://your-mcp-server:port/mcp).

Installation

Set up a project: Create a new project directory and initialize it with Node.js:

mkdir intuition-mcp-client
cd intuition-mcp-client
npm init -y
npm install @modelcontextprotocol/sdk

Install dependencies: The @modelcontextprotocol/sdk package includes the necessary modules for both Streamable HTTP and SSE transports.

Example Client Setup

Below is an example of a Node.js client using the MCP SDK to connect to the Intuition MCP Server and interact with its tools.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

async function connectToMcpServer(url) {
  let client;
  const baseUrl = new URL(url);

  try {
    // Attempt to connect using Streamable HTTP transport
    client = new Client({
      name: 'streamable-http-client',
      version: '1.0.0',
    });
    const transport = new StreamableHTTPClientTransport(baseUrl);
    await client.connect(transport);
    console.log('Connected using Streamable HTTP transport');
    return client;
  } catch (error) {
    console.log(
      'Streamable HTTP connection failed, falling back to SSE transport:',
      error.message
    );
    // Fallback to SSE transport for legacy compatibility
    client = new Client({
      name: 'sse-client',
      version: '1.0.0',
    });
    const sseTransport = new SSEClientTransport(baseUrl);
    await client.connect(sseTransport);
    console.log('Connected using SSE transport');
    return client;
  }
}

async function callMcpTool(client, toolName, payload) {
  try {
    // Send a request to the specified tool
    const response = await client.callTool(toolName, payload);

    // Handle streaming response
    response.on('data', (data) => {
      console.log('Received data:', data);
    });

    response.on('end', () => {
      console.log('Stream ended');
    });
  } catch (error) {
    console.error('Error calling MCP tool:', error.message);
  }
}

// Example usage
async function main() {
  const serverUrl = 'http://your-mcp-server'; // Replace with your server URL
  const client = await connectToMcpServer(serverUrl);

  // Example: Search for atoms related to Ethereum
  await callMcpTool(client, 'search_atoms', { queries: ['ethereum', 'eth'] });

  // Example: Extract triples
  await callMcpTool(client, 'extract_triples', { input: 'Alice knows Bob' });
}

main().catch(console.error);

Making API Requests

Initialize the client:

Create an MCP Client instance and connect it to the server using either StreamableHTTPClientTransport or SSEClientTransport.

The client automatically handles transport negotiation and fallback to SSE if Streamable HTTP fails.

Construct the payload:

Use the input schema for the desired tool (e.g., {"queries": ["ethereum"]} for search_atoms).

Ensure the payload matches the tool’s JSON schema to avoid errors.

Send the request:

Use the client.callTool method to invoke a tool with the specified payload.

The client handles the underlying HTTP or SSE communication, including streaming responses.

Handle the response:

Responses are streamed and can be processed using event listeners (e.g., response.on('data', ...)).

Parse each chunk as JSON if the response is structured data.

Handle the end event to detect when the stream is complete.

Example Payloads:

For search_atoms:

await client.callTool('search_atoms', { queries: ['blockchain'] });

For get_account_info:

await client.callTool('get_account_info', {
  identifier: '0x1234567890123456789012345678901234567890',
});

Notes

Server URL: Replace http://your-mcp-server with the actual server address.

Authentication: If the server requires an API key, configure it in the transport options (consult the MCP SDK documentation for details).

Error Handling: The client automatically retries with SSE transport if Streamable HTTP fails (e.g., due to a 4xx error).

Streaming: Ensure your application can handle streaming responses, as large datasets are returned incrementally.

Legacy Support: The server supports both Streamable HTTP and SSE transports for backwards compatibility with older clients.

Deployment

This repository contains a sample Dockerfile that you can use to deploy to services such as Render or any other host provider that supports Docker. The Dockerfile is already configured to work for deploying the project structure as is. If you make any changes to the repo structure after cloning you'll want to be sure to update this file.

We've included a render.yaml file for the public deployment. We invite you to create your own deployment. You can utilize our existing render.yaml file to deploy your own Render project.

Contributing

Contributions to the Intuition MCP Server are welcome! To contribute:

  • Fork the repository.

  • Create a feature branch (git checkout -b feature/your-feature).

  • Commit your changes (git commit -m "Add your feature").

  • Push to the branch (git push origin feature/your-feature).

  • Open a pull request.

Please ensure your code follows the project's coding standards and includes tests.

License

The Intuition MCP Server is licensed under the MIT License (LICENSE). See the LICENSE file for details.

Available Tools

6 tools
get_account_infoA

Get account information by address or identifier. Returns account details, relationships/claims (semantic triples), financial positions, and associated atoms. Works best with wallet addresses (0x...). For comprehensive ENS data, search_atoms provides richer relationship discovery.

NameRequiredDescriptionDefault
addressNo
identifierNo

TDQS

A4/5.0
Behavior3/5

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

With no annotations, the description carries the full burden, and it does disclose the response payload categories, which is genuinely useful. It does not state that the operation is read-only (only implied by 'Get'), nor what happens for an unknown address, whether lookups are rate-limited or permissioned, or whether both parameters can be passed together — meaningful gaps for a lookup tool with zero annotation coverage.

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 short sentences: purpose, return contents, then the addressing hint and sibling alternative. The most decision-relevant information is front-loaded and nothing is redundant or padded.

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?

No output schema exists, and the description compensates by listing the returned data categories, so an agent can reason about results. The remaining hole is parameter behavior (address vs identifier, both/neither cases) plus any precondition or failure-mode context, which keeps it from being fully complete.

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 coverage is 0% and neither parameter has a description, so the description must compensate; it does partially by naming both inputs and giving a format hint for 'address' (0x...). It never explains what an 'identifier' is, how it differs from an address, or the precedence when both are supplied, leaving half the parameter surface underspecified.

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?

States a specific verb and resource ('Get account information') and enumerates the returned payload (account details, relationships/claims, financial positions, associated atoms), so the agent knows exactly what the tool produces. It also names a sibling, search_atoms, and the condition under which that sibling is preferred, which separates it from the other account-oriented tools in the list.

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?

Gives a clear usage hint ('Works best with wallet addresses (0x...)') and an explicit alternative for ENS data ('search_atoms provides richer relationship discovery'). It stops short of saying when to use 'identifier' instead of 'address' or what happens when both/neither are supplied, so the guidance is strong but not exhaustive.

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

get_followersB

Get followers of an address and their relationships/interactions. Returns follower accounts with their activities and connections for social network analysis.

NameRequiredDescriptionDefault
predicateNoOptional predicate to filter followers positions on. Example: recommend, follow, like, dislike
account_idYesThe account id of the account to find the followers for. Example: 0x3e2178cf851a0e5cbf84c0ff53f820ad7ead703b

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations, the description carries the full behavioral burden. It discloses that the response includes nested activities and connections, which is useful, but says nothing about result size, pagination, depth limits, or cost of traversing a graph — all material for a potentially heavy read operation.

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 compact sentences with the core action front-loaded and no filler. There is mild redundancy between 'relationships/interactions' and 'activities and connections', but it costs little.

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?

For a two-parameter read tool with no annotations and no output schema, the description covers what the tool does and roughly what it returns. It falls short on operational detail — pagination, volume, or what 'connections' actually contains — which an agent would need before calling it on a large account.

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 coverage is 100%, so both account_id and predicate are already documented with examples in the schema. The description adds no meaning beyond that baseline and never explains what filtering by predicate does to the returned follower set.

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 states a specific verb and resource ('Get followers of an address') and adds what comes back ('follower accounts with their activities and connections'). It is clearly distinguishable from the inverse sibling get_following by name, though it never explicitly contrasts itself with it.

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 closing phrase 'for social network analysis' implies a use context, but there is no explicit when-to-use, when-not-to-use, or named alternative such as get_following or get_account_info. The agent must infer selection from the tool names alone.

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

get_followingB

Get accounts that a given address is following and their relationships. Returns followed accounts with their activities and connections for social graph analysis.

NameRequiredDescriptionDefault
predicateNoOptional predicate to filter following positions on. Example: recommend, follow, like, dislike
account_idYesThe account id of the account to find the following for. Example: 0x3e2178cf851a0e5cbf84c0ff53f820ad7ead703b

TDQS

B3.4/5.0
Behavior3/5

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

No annotations are supplied, so the description carries the full disclosure burden, and it does state what comes back: followed accounts plus their activities and connections. It says nothing about result volume, pagination, ordering, or whether the traversal is bounded, which matters for a graph-expansion call that can return large payloads.

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 sentences with the core operation front-loaded and no filler. The second sentence is somewhat redundant with the first, restating the return content in slightly different terms, but it is not wasteful enough to hurt.

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?

With no annotations and no output schema, the description does the minimum needed to explain the result shape and its analysis purpose. It leaves out practical call details such as result size behavior and whether connections are expanded recursively, which an agent would want before invoking a graph query.

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 description coverage is 100%, so both account_id and predicate are already documented with examples, making 3 the baseline. The description adds no meaning beyond the schema and notably never mentions the predicate filter, which is the only parameter whose effect is non-obvious.

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 states a specific verb and resource: 'Get accounts that a given address is following,' which reads as the mirror of the sibling get_followers. It adds scope detail ('their relationships') but never explicitly names get_followers or any sibling as the contrasting choice, so differentiation is implied by wording rather than stated.

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?

Usage is only implied through the phrase 'for social graph analysis,' which gives a loose context but no explicit when-to-use or when-not-to-use conditions. It never tells the agent to prefer get_followers for the inverse direction or another sibling for plain account lookups.

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

search_account_idsB

Search for account addresses by ENS name or identifier. Returns the wallet address for the given identifier.

NameRequiredDescriptionDefault
identifierYesThe account identifier to search the id for, typically an ens address. Example: intuitionbilly.eth

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations, the description carries the full burden and does state the core behavior: it resolves an identifier to a wallet address. It leaves important traits unstated, though: whether the lookup is an exact resolve or a fuzzy search (the word 'search' suggests one thing, 'for the given identifier' another), what happens when nothing matches, and whether ENS resolution involves network calls or latency.

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 short sentences with the purpose front-loaded and no filler. The second sentence partly restates the first's implication, but the definition is still well within an appropriate size.

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?

For a single-parameter lookup with a fully described schema and no output schema, stating the return value covers a lot. It still omits not-found behavior and match semantics, which are exactly the details an agent needs before calling a 'search' tool that returns a single address.

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 description coverage is 100%, and the schema already says the identifier is 'typically an ens address' with an example, so the baseline of 3 applies. The description adds no format, normalization, or matching semantics beyond what the schema field documents.

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?

It states a concrete verb and resource ('Search for account addresses by ENS name or identifier') and the return ('wallet address'), so the agent knows exactly what the tool produces. It falls short of a 5 because it never differentiates itself from the sibling get_account_info, which an agent could plausibly pick for the same account lookup.

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 input domain ('ENS name or identifier') implies when the tool applies, which is the definition of implied usage. It never says when to prefer this over get_account_info or search_atoms, and gives no exclusions or prerequisites, so routing between siblings is left to guesswork.

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

search_atomsB

Search entities (accounts, things, people, concepts) by name, description, URL, or ENS domain. Returns entity info, rich relationship data (as_subject_triples), and financial data (market cap, shares). Excellent for ENS names, discovering social connections, and semantic relationships. Supports synonyms and keyword variations.

NameRequiredDescriptionDefault
queriesYes

TDQS

B3.4/5.0
Behavior3/5

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

With no annotations, the description carries the full disclosure burden. It does usefully preview the return payload (entity info, as_subject_triples relationship data, financial fields like market cap and shares), but says nothing about result limits, ordering, pagination, or whether a multi-query request merges or keeps separate result sets.

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?

Four compact sentences, front-loaded with what is searched, then what is returned, then when it shines. The as_subject_triples parenthetical and financial-field list are dense but each earns its place by telling the agent what it will get back.

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?

For a single-parameter search tool with no annotations and no output schema, the description does a reasonable job on the return side but leaves the input contract unexplained. An agent knows what to expect back but not how to shape a multi-query request or interpret its results.

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 single parameter `queries` has 0% schema coverage — no description, no item semantics — and the description never mentions it. The agent cannot tell from either source that the input is an array of search strings, how multiple queries are combined, or how results map back to each query.

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 gives a specific verb (search) and names the resource types covered (accounts, things, people, concepts) plus the matchable fields (name, description, URL, ENS domain). It is clearly a broad entity search, which implicitly separates it from narrower siblings like search_account_ids and search_lists, though it never names them explicitly.

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?

It offers positive usage signals — 'Excellent for ENS names, discovering social connections, and semantic relationships' — which tell the agent what this tool is good at. It stops short of explicit when-not guidance or pointing to any of the five sibling tools as an alternative.

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

search_listsB

Search for curated lists of entities by name or topic. Returns lists with their items sorted by relevance.

NameRequiredDescriptionDefault
queryYesThe search query to find lists by object label

TDQS

B3.3/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that results contain lists with items and are sorted by relevance, but omits permissions, pagination, result limits, and empty-result behavior.

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 short sentences, front-loaded with the purpose and followed by return behavior. Every sentence carries useful information and there is no filler.

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?

For a simple one-parameter search tool this covers the basic purpose and return ordering. However, with no output schema, it should say more about result shape, pagination, and limits to be fully self-sufficient.

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?

The single query parameter is fully documented in the schema, so the baseline is 3. The description adds slight nuance by saying matching is by name or topic rather than only schema wording 'object label', but it does not explain matching semantics such as exact vs fuzzy search.

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 states a specific verb ('search') and resource ('curated lists of entities'), including that matching is by name or topic. This is clear enough to separate it from sibling search tools like search_atoms, though it never explicitly contrasts with them.

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?

It implies usage by saying lists can be searched by name or topic, but gives no explicit guidance on when to choose this tool over search_atoms or search_account_ids. There are no exclusions, prerequisites, or alternative-routing instructions.

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.9.0
    • First observedget_account_info
    • First observedget_followers
    • First observedget_following
    • First observedsearch_account_ids
    • First observedsearch_atoms
    • First observedsearch_lists

TDQS

A3.6/5.0

Scored across 6 tools

Disambiguation3/5

The social graph tools (get_following/get_followers) and search_lists are clearly distinct. However, search_atoms, get_account_info, and search_account_ids all overlap around resolving accounts/entities by ENS or identifier, even though the descriptions attempt to guide selection.

Naming Consistency5/5

All tool names use a consistent snake_case verb_noun pattern (search_atoms, get_account_info, search_lists, get_following, get_followers, search_account_ids). The verbs are predictable and readable.

Tool Count5/5

Six tools is well-scoped for an entity/social-graph query server. Each tool maps to a recognizable operation: entity search, account lookup, list search, following, followers, and identifier resolution.

Completeness3/5

The read-only discovery surface covers core search and social graph needs, but there are notable gaps: no direct get-atom-by-ID, no dedicated list detail/items retrieval, no explicit triple/relationship search, and no write or mutation operations if the domain requires them.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables creation and management of knowledge graphs with entities, relationships, and observations through HTTP streaming. Supports persistent storage, search functionality, and CRUD operations for building and querying interconnected knowledge bases.
    2
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    A shared knowledge graph memory MCP server that multiple AI clients can connect to simultaneously via Streamable HTTP, supporting entity-relation storage and retrieval.
    -
  • A
    license
    A
    quality
    C
    maintenance
    Enables querying of a fictional CRM knowledge graph of enterprise accounts and their contacts, with tools for listing, searching, retrieving full record details, and running read-only SPARQL queries. Clients such as Claude, ChatGPT, or Adobe Coworker can connect over remote HTTP or local stdio, optionally protected by OAuth.
    9
    GPL 3.0