Cosmonauth

Connect your API

Make your API accessible to MCP servers that LLMs can use.

Prerequisites

1 - Register your API

  1. Go to your home page
  2. Click Connect your API in the left sidebar
  3. Fill in the form with your API details

You can leave authentication to none for now. Your API is by default private and visible to your account only.

2 - Define your tools

Cosmonauth will send GET requests to your API URL to discover what tools you provide. You need to implement a GET endpoint that returns a list of tools.

Example

Let’s say your API URL is https://random-color.com/tools and you want to provide a tool which returns a random color based on a number, then sending a GET request to your API URL should return a list of tools like:

[
  {
    "name": "get",
    "description": "Get a random color based on a number",
    "input_schema": {
      "type": "object",
      "properties": {
        "number": {
          "type": "number",
          "description": "The number to get a color for"
        }
      },
      "required": ["number"]
    }
  }
]

The input schema structure follows the official MCP Documentation. You can read more about it here

3 - How tools are called

When an LLM wants to use your tool, Cosmonauth will send a POST request to your API URL with the following structure:

{
  "name": "get",
  "args": {
    "number": 42
  }
}

Your API should:

  1. Extract the name and args from the request body
  2. Execute the corresponding tool logic
  3. Return the result as JSON

Example implementation

app.post('/tools', (req, res) => {
  const { name, args } = req.body

  if (name === 'get') {
    const { number } = args
    const colors = ['red', 'blue', 'green', 'yellow', 'purple']
    const color = colors[number % colors.length]

    res.json({ color, number })
  } else {
    res.status(404).json({ error: 'Tool not found' })
  }
})

4 - Scan your tools

  1. Go to your home page
  2. Click on your API from the list
  3. Click on the Scan button

Your tools are now listed and ready to be used by LLMs.

Cosmonauth cache your tool definitions to avoid spamming your API. Whenever a change occurs to your tool definitions, you need to click on the Scan button again to refresh the list.

5 - Authentication

Cosmonauth supports three authentication modes for your API:

None

Use this for public APIs that don’t require authentication.

API Key

Use this if you want to use Cosmonauth built-in access controls.

Cosmonauth will generate a unique API key for each LLM connecting to your API and set it in the request headers x-cosmo-api-key.

Credentials

Use this if you want to manage your own access controls.

You can give write instructions to your users on how to generate credentials for your API.

A JSON textarea will be shown to your users where they can paste their credentials.

The JSON expects an object where each key is a header name and the value is the header value.

Example:

The following credentials

{
  "api_key": "1234",
  "secret-key": "abcde",
  "whatever_you-want": "..."
}

Gives the following headers:

{
  "x-cosmo-api-key": "1234",
  "x-cosmo-secret-key": "abcde",
  "x-cosmo-whatever-you-want": "..."
}

Headers will be prefixed with x-cosmo- to avoid conflicts with your own headers and transformed to kebab-case.

6 - Visibility

By default your API is private and only visible to you.

You can change this in the API settings and make it public.

Public APIs will be visible in the store and other users will be able to connect their LLM to it.

Next Steps

Your API is now listed, connect your LLM to start using it.