# MCP Marketplace API Document

MCP Marketplace is python/node packages to allow you to get access to MCP Servers Config and tools schemas from open mcp marketplace of various endpoints.
It can be easily integrated in your LLM and AI application workflow, including Get, LIST, UPDATE , CREATE and DELETE Your MCP Servers, which can also give
user reviews, ratings and github stars and many metrics to allow LLM to choose wisely.

## [API V1](#api_v1)


### 1. MCP SERVER 
GET MCP Marketplace Server Meta Information
```http
GET /api/mcp_marketplace/v1?mode=list&query=map&page_id=0&count_per_page=5
```

**Curl**
```http
curl 'https://www.deepnlp.org/api/mcp_marketplace/v1?mode=list&query=map&page_id=0&count_per_page=5'
```


**Parameters**

| Parameter      | type   | value                                              |
|----------------|--------|----------------------------------------------------|
| query          | string | /api/mcp_marketplace/v1?query=map                  |
| category       | string | /api/mcp_marketplace/v1?category=map               |
| list all       | string   | /api/mcp_marketplace/v1?                           |
| page_id        | int    | /api/mcp_marketplace/v1?page_id=0&count_per_page=5 |
| count_per_page | int    | /api/mcp_marketplace/v1?page_id=0&count_per_page=5 |
| offset         | int    | /api/mcp_marketplace/v1?offset=0 |
| mode           | string    | mode='list' or 'dict' |


**Results**
```
{
  "query": "map",
  "items": [
      {
        "content_name": "MCP SERVER Markdown Demo",
        "publisher_id": "pub-user-agent-v1",
        "website": "",
        "review_cnt": "0",
        "subfield": "MAP",
        "field": "MCP SERVER",
        "rating": "0.0",
        "id": "user-agent-v1/mcp-server-markdown-demo",
        "content_tag_list": "AI AGENT",
        "content": "",
        "content_description": "## Demo description",
        "thumbnail_picture": ""
      }
  ],
  "count": 1,
  "total_hits": 20
}

```

## Supported API Summary

| Scenario | Mode | Endpoint                                                                               | Description                                        |
| ---- | ---- |----------------------------------------------------------------------------------------|----------------------------------------------------|
| Search by Unique ID  | MODE=LIST  | GET /api/mcp_marketplace/v1?mode=list&id=google-maps/google-maps                       | -                                                  |
| Search by Unique ID	| MODE=DICT  | GET /api/mcp_marketplace/v1?mode=dict&id=google-maps/google-maps                       | -                                                  | 
| Search by Query |  MODE=LIST  | GET /api/mcp_marketplace/v1?mode=list&page_id=0&count_per_page=20&query=coding%20agent | When you want to search Coding Agent related       | 
| Search by Query |  MODE=DICT  | GET /api/mcp_marketplace/v1?mode=dict&page_id=0&count_per_page=20&query=coding%20agent | Suitable for Search By Group Name                  | 
| No Query, Pagination |  MODE=LIST  | GET /api/mcp_marketplace/v1?mode=list&page_id=0&count_per_page=20                      | Explore AI Agents By various Category, Return List | 
| No Query, Pagination |  MODE=DICT | GET /api/mcp_marketplace/v1?mode=dict&page_id=0&count_per_page=20                      | Explore AI Agents By various Category, Return Map  | 



### [Search by Unique ID](#search_unique_id)

The unique id of agent meta usually follows the github or nodejs schema, such as unique_id="{owner}/{repo_name}"

| Parameter | type   | value                                                  |
|-----------|--------|--------------------------------------------------------|
| id        | string | unique id of the item, unique_id="{owner}/{repo_name}" |
| return_fields | string | optinal, e.g. return_fields=tools,config               |

**List Mode**

http
```http
GET /api/mcp_marketplace/v1?mode=list&id=google-maps/google-maps
```

Curl
```http
curl 'https://www.deepnlp.org/api/mcp_marketplace/v1?mode=list&id=google-maps/google-maps'
```

**Dict Mode**
http
```http
GET /api/mcp_marketplace/v1?mode=dict&id=google-maps/google-maps
```

Curl
```http
curl 'https://www.deepnlp.org/mcp_marketplace/v1?mode=dict&id=google-maps/google-maps'
```


### [Search by Query](#search_query)

| Parameter      | type   | value                                                           |
|----------------|--------|-----------------------------------------------------------------|
| query | string | string of query                                                 |
| page_id        | int    | current id of page                                              |
| count_per_page | int    | default count of items per page.                                |
| offset         | int    | number of items to skip, equivalent to page_id * count_per_page |
| return_fields | string | optinal, e.g. return_fields=tools,config               |

**List Mode**
http
```http
GET /api/mcp_marketplace/v1?mode=list&query=coding agent&page_id=0&count_per_page=5
```

Curl
```http
curl 'https://www.deepnlp.org/api/mcp_marketplace/v1?mode=list&query=coding agent&page_id=0&count_per_page=5'
```


**Dict Mode**
http
```http
GET /api/mcp_marketplace/v1?mode=dict&query=coding agent&page_id=0&count_per_page=5
```

Curl
```http
curl 'https://www.deepnlp.org/mcp_marketplace/v1?mode=dict&query=coding agent&page_id=0&count_per_page=5'
```


### [Pagination Exploration with No Query](#pagination_no_query)

| Parameter      | type   | value                                   |
|----------------|--------|-----------------------------------------|
| page_id        | int    | current id of page                      |
| count_per_page | int    | default count of items per page.        |
| offset         | int    | number of items to skip, equivalent to page_id * count_per_page |


**List Mode**

http

```http
GET /api/mcp_marketplace/v1?mode=list&page_id=0&count_per_page=5
```

Curl

```http
curl 'https://www.deepnlp.org/api/mcp_marketplace/v1?mode=list&page_id=0&count_per_page=5'
```

**Dict Mode**

http

```http
GET /api/mcp_marketplace/v1?mode=dict&page_id=0&count_per_page=5
```

Curl

```http
curl 'https://www.deepnlp.org/api/mcp_marketplace/v1?mode=dict&page_id=0&count_per_page=5'
```


## MCP Config <code>mcp.config</code> API

Base API Endpoint
```http
GET /api/mcp_marketplace/v1/server/${owner_id}/${repo_name}
```

Sample Server Config
```http
GET /api/mcp_marketplace/v1/server/ai-hub-admin/mcp-server-v1
```
**Parameters**

The uniqueId of MCP Server we use the github or nodejs owner_id and repo_name
For example, for a demo server maintained here: http://www.github.com/ai-hub-admin/mcp-server-v1

| Parameter | type   | value         |
|-----------|--------|---------------|
| owner_id  | string | ai-hub-admin  |
| repo_name | string | mcp-server-v1 |
| id        | string   | ai-hub-admin/mcp-server-v1 |

**Results**

```
{"total_hits":1,
"id":"ai-hub-admin/mcp-server-v6",
"items":
[
    {
        "content_name":"MCP SERVER V6","publisher_id":"pub-ai-hub-admin","website":"http://www.markdown.com","review_cnt":"0","rating":"0.0","description":"This is MCP Server V6\r\n\r\n### Hahaha\r\n\r\n\r\n","ext_info":{"tools":[]},"subfield":"MCP SERVER","field":"MCP SERVER","id":"ai-hub-admin/mcp-server-v6","content_tag_list":"MCP SERVER",
        "config":[
            {
                "mcpServers":{
                    "command": "npx",
                    "arguments": [],
                    "env": {}
                }
            }
            {
                "mcpServers":{
                    "command": "docker",
                    "arguments": [],
                    "env": {}
                }
            }      
        ],
        "thumbnail_picture":""
    }
]
}
```

### Tools
#### List MCP Marketplace Tools

```http
GET /api/mcp_marketplace/v1/tools/${owner_id}/${repo_name}
```

```http
GET /api/mcp_marketplace/v1/tools/ai-hub-admin/mcp-server-v1
```

Fill The MCP Tools Schema of Your MCP Server for LLM or AI Agent function calls API

**Results**
```
{"id":"ai-hub-admin/mcp-server-v1",
    "tools":
    [{  "name":"tool1",
       "description":"This is Schema for tool1",
       "inputSchema":{"type":"object"}},
     {  "name":"tool2",
        "description":"This is Schema for tool2",
        "inputSchema":{"type":"object"}}
    ]
}
```