agentcore-register

AgentCore Register

Given a remote MCP server URL, probe it to discover server info and tools, then generate a markdown file containing copy-pasteable values for every field in the Amazon Bedrock AgentCore Create record form.

The MCP server URL is provided as $ARGUMENTS.

If $ARGUMENTS is empty, ask the user for the MCP server URL using AskUserQuestion.

Steps

1. Initialize the MCP session

Send the MCP initialize request and capture the response headers (for the session ID) and body (for server info).

curl -s --max-time 15 -D /tmp/_agentcore_mcp_headers.txt \
  -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "agentcore-register", "version": "1.0.0"}
    }
  }' > /tmp/_agentcore_mcp_init.json 2>&1

Parse the response to extract:

• serverInfo.name - the server name
• serverInfo.version - the server version
• protocolVersion - the MCP protocol version
• capabilities - what the server supports

Extract the mcp-session-id header value from /tmp/_agentcore_mcp_headers.txt.

Error handling

• If the curl request fails or times out, tell the user the server is unreachable and stop.
• If the response is a 502/503/504, tell the user the server backend is down and stop.
• If the response is HTML (not JSON), tell the user the URL may not be an MCP endpoint and stop.

2. List the tools

Using the session ID from step 1, send a tools/list request:

SESSION_ID=$(grep -i 'mcp-session-id' /tmp/_agentcore_mcp_headers.txt | awk '{print $2}' | tr -d '\r')

curl -s --max-time 15 \
  -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/list", "params": {}}' \
  > /tmp/_agentcore_mcp_tools.json 2>&1

The response may be plain JSON or SSE-formatted (data: {...}). Handle both:

• If the response starts with {, parse it directly as JSON.
• If the response contains data: lines, extract the JSON from the data: line.

Parse the tools array from result.tools. For each tool, capture:

• name
• description
• inputSchema (the full JSON schema object)

3. Generate the markdown file

Create a markdown file at .scratchpad/agentcore-register-<server-name>.md with all the values the user needs to copy-paste into the AgentCore form.

Use this exact template, replacing placeholders with the discovered values:

# AgentCore Registry Record: <server_name>

*Generated: <current date>*
*Source: <MCP_URL>*

---

## Record Details

**Name:**

<server_name as a valid record ID, e.g. record_novacolor_finishes>

**Description:**

<server description derived from tools and server name, 1-2 sentences>

**Record version:**

<server version, e.g. 0.1>

**Record type:** MCP

---

## MCP Server Definition

Copy-paste the JSON below into the "Your MCP server definition" editor:

```json
{
  "name": "<namespace/slug, must match ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$>",
  "description": "<max 100 chars, concise description>",
  "version": "<version>",
  "remotes": [
    {
      "type": "<transport type, e.g. streamable-http>",
      "url": "<MCP_URL>"
    }
  ]
}

---

Tool Definition

Copy-paste the JSON below into the "Your Tool definition" editor:

{
  "tools": [
    <for each tool, include the full tool object with name, description, and inputSchema>
  ]
}

---

Discovery Summary

Field	Value
Server name	<serverInfo.name>
Version	<version>
Protocol	<protocolVersion>
Transport	<transport type>
URL	<MCP_URL>
Tools
Capabilities

#### Rules for populating the template

- **Record name**: Convert the server name to a valid AgentCore record ID. Use lowercase, replace spaces and hyphens with underscores, prefix with `record_`. Only use letters, digits, underscores. Example: `record_novacolor_finishes`.
- **Description**: Write a concise 1-2 sentence description based on the server name and tool names/descriptions.
- **Transport**: Determine from how the server responded:
  - If the initialize response included `mcp-session-id` header and responded to POST with JSON, use `streamable-http`.
  - If the server used SSE (event-stream responses for initialize), use `sse`.
  - Default to `streamable-http` for remote HTTP servers.
- **MCP server definition JSON**: Must include `name`, `description`, `version`, and `remotes` fields. The `remotes` array contains the transport type and URL so that the AgentCore sync can extract `proxy_pass_url` correctly via `remotes[0].url`.
  - **name** MUST match the pattern `^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$` (namespace/name format). Derive the namespace from the server's domain (e.g., `com.agenthost` for `agenthost.club`, `io.github.user` for GitHub). Example: `com.agenthost/novacolor-italian-finishes`.
  - **description** MUST be 100 characters or fewer. Keep it concise.
  - **remotes** MUST be an array with at least one object containing `type` (transport type) and `url` (the MCP endpoint URL). Do NOT use top-level `url` and `transport` fields -- use the `remotes` array format instead.
- **Tool definition JSON**: Include the complete tool objects exactly as returned by the server, wrapped in a `{"tools": [...]}` envelope.
- **Tool inputSchema**: Include the full inputSchema for each tool exactly as returned by the server. Do NOT simplify or omit properties.

### 4. Cleanup

Remove temporary files:

```bash
rm -f /tmp/_agentcore_mcp_headers.txt /tmp/_agentcore_mcp_init.json /tmp/_agentcore_mcp_tools.json

5. Report to the user

After generating the file, display:

1. The path to the generated markdown file.
2. A brief summary: server name, number of tools, transport type.
3. Tell the user they can open the file and copy-paste each section into the AgentCore "Create record" form.

Example

User: /agentcore-register https://novacoloritalianfinishes.agenthost.club/mcp

Output:
Generated `.scratchpad/agentcore-register-novacolor.md`

Summary:
- Server: some-agent (v0.1)
- Transport: streamable-http
- Tools: 3 (search_site_products, search, fetch)

Open the file and copy-paste each section into the AgentCore "Create record" form.