Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.ambersearch.de/llms.txt

Use this file to discover all available pages before exploring further.

Model Context Protocol (MCP) is a standardized way to add extra context to LLMs via external data sources and tools. Simply put, with using various MCP servers, you can have your LLM interact with your GitLab, search the web, find places on a map, and more. MCP servers are designed to be easy as possible to set up and use, so you can integrate them into your applications quickly.

​
Getting Started

We have set up the MCP server to be accessible through a remote URL, so you can start using it right away, without needing to install anything locally. The server is available at: 
https://customerDomain.ambersearch.de/mcp/

​
Authentication

The authentication for the MCP server is the same as for the public REST API. You will need to provide your API key or a jwt through the OAuth 2 flow in the Authorization header of your requests with the Bearer scheme. In addition to the normal OAuth2 flow where the client credentials get passed, the OAuth 2 flow for the MCP server includes discovery endpoints for the authorization server as referred to in the authorization manual.

​
MCP Client Integration

​
Step 1: OAuth discovery

In order to initiate an authorization flow it is required to discover its OAuth configuration. Given the MCP server URL (e.g., https://customerDomain.ambersearch.de/mcp), use a standard two-step discovery process:
  1. Based on RFC 9470: Fetch Protected Resource Metadata to find which authorization server(s) protect this resource
  2. After retrieving the protected resource metadata the authorization server metadata endpoint can be extracted, based on RFC 8414
The Protected Resource Metadata tells you where to find the authorization server, and the Authorization Server Metadata tells you the specific OAuth endpoints to use. Thus an initial handshake is required to get the Protected Resource Metadata by hitting the /mcp endpoint, the expected result from this handshake is a status code 401 and a WWW-Authenticate HTTP header with the resource metadata, refer to this. 
GET /mcp
Response: 
{
    "error": "invalid_token",
    "error_description": "Authentication failed. The provided bearer token is invalid, expired, or no longer recognized by the server. To resolve: clear authentication tokens in your MCP client and reconnect. Your client should automatically re-register and obtain new tokens."
}
Response Headers: 
{
    "Content-Type": "application/json"
    "Connection": "keep-alive"
    "WWW-Authenticate": "Bearer error="invalid_token", error_description="Authentication failed. The provided bearer token is invalid, expired, or no longer recognized by the server. To resolve: clear authentication tokens in your MCP client and reconnect. Your client should automatically re-register and obtain new tokens.", resource_metadata="https://customerDomain.ambersearch.de/.well-known/oauth-protected-resource/mcp"
    ...
}

GET /.well-known/oauth-protected-resource/mcp
Accept: application/json
Response: 
{
    "resource": "https://customerDomain.ambersearch.de/mcp",
    "authorization_servers": [
        "https://customerDomain.ambersearch.de/"
    ],
    "scopes_supported": [],
    "bearer_methods_supported": [
        "header"
    ],
    "resource_name": "AmberSearch MCP Server"
}

​
Step 2: Initiate the OAuth 2 flow

After retrieving the authorization server metadata from the authorization server metadata endpoint, the client can initiate the authorization flow as referenced in the ambersearch OAuth 2 manual with either PKCE or client_secret.

​
Configuration

Most of the applications use the same configuration format for handling MCP servers. Here’s a sample configuration that you can use to set up your MCP client to connect to the AmberSearch MCP server: 
{
    "mcpServers": {
        "ambersearch": {
            "transport": "http",
            "url": "https://customerDomain.ambersearch.de/mcp/",
            "headers": {
                "Authorization": "Bearer ambrs-exampletoken"
            }
        }
    }
}

{
    "mcpServers": {
        "ambersearch": {
            "transport": "http",
            "url": "https://customerDomain.ambersearch.de/mcp/",
            "headers": {
                "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
            }
        }
    }
}

​
Tools

The AmberSearch MCP server provides the following tools:
Tool NameDescription
searchSearch for data across multiple data sources.
web_searchPerform a web search using specified queries and parameters.
get_document_metadataRetrieve metadata for a specific document.
Detailed descriptions of the tools and their parameters are as follows:
  • search - Search for data across multiple data sources.
    • query: The search term to look for (string, required)
    • count: The number of results to return (number, optional)
    • data_source: The data source to search in (string, optional)
    • file_type: The type of files to search for (string, optional)
    • last_modified_date: The time frame for the last modified date (string, optional)
    • start_page: The page number to start from (number, optional)
  • web_search - Perform a web search using the provided queries and parameters.
    • queries: A list of search queries (array of strings, required)
    • count: The number of results to return (number, optional)
    • sites: A list of specific sites to search within (array of strings, optional)
    • timeout: The maximum time to wait for the search results in seconds (number, optional)
  • get_document_metadata - Retrieve metadata for a specific document.
    • document_id: The unique identifier of the document (string, required)
    • provide_text_attribute: Whether to include the document’s text content in the response (boolean, optional)